Celestin Apprentice 5/Apprentice-Release5.iso/Source Code/C/Games/Xconq 7.1.0/src/xconq-7.1.0/doc/refman.texi

Text File | 1996-07-07 | 221.8 KB | 6,581 lines | [TEXT/R*ch]

@node Reference Manual

@chapter Reference Manual

This manual is the complete description of GDL.
The style is somewhat terse; for more detail on how to
use GDL to design games, see Chapter 3.

Please note that the current version of @i{Xconq} may not fully
implement all of the constructs or combinations of constructs
described here.  Any such omissions should be regarded as bugs.

@menu
* Language Syntax::
* Game Module Forms::
* World and Area Forms::
* Side and Player Forms::
* Unit Forms::
* Agreements::
* Scorekeeper Forms::
* History Forms::
* Battle Forms::
* Types in General::
* Unit Types::
* Terrain Types::
* Material Types::
* Static Relationships Between Types::
* Vision::
* Game Initialization::
* Synthesis Methods::
* Setup Postprocessing::
* Naming and Text Generation::
* Actions::
* Backdrop Environment Parameters::
* Backdrop Economy Parameters::
* Random Events::
* Dates and Time::
* Image Families::
* Other Forms::
* Files and Directories::
@end menu

@node Language Syntax, Game Module Forms, , Reference Manual

@section Language Syntax

GDL resembles Lisp, but instead of defining functions,
the contents of a file declare
certain objects (such as units and unit types) to exist,
and specify values for their properties.
In other words, GDL is @emph{nonprocedural}.
This means that most of the time, you can list the various
forms in any order you like.
The main restriction is that any symbol, such as a variable
or the name of a type, must be defined before it is used.
Also, forms such as @code{set} and @code{add}, that set the
value of a variable or property,
always overwrite the previous data irreversibly,
so ordering of these is very important.

@menu
* Lexical Elements::
* Conventions Used::
* Forms and Evaluation::
* Tables::
* Modifying Objects::
* Symbols::
* Lists::
@end menu

@node Lexical Elements, Conventions Used, Language Syntax, Language Syntax

@subsection Lexical Elements

Numbers are introduced by a decimal digit, plus, or minus signs.
They may contain only decimal digits, a decimal point, and be followed
(immediately, no whitespace allowed) by a percent sign.

Strings are sequences of characters enclosed by doublequotes (@code{"}).
They may contain any character except ASCII NUL (@code{'\0'}).
To include a doublequote, use backslash, as in @code{"a \"quoted\" string"}.
To include a nonprinting or eight-bit character,
use backslash followed by three octal
digits, which will be interpreted as an eight-bit character code.
(This is mostly the same syntax as in C.)
Note that game design files may be passed over networks
and between different kinds of computer systems,
so non-ASCII characters should not be inserted verbatim into strings.

Symbols are sequences of characters that don't
include any of the other special characters.  If you wish to include such
characters in a symbol, enclose it in vertical bars,
for example @code{|foo bar|}.
(The bars are not part of the symbol.)
Symbols are case-sensitive,
but this will be changed eventually.

Lists are a sequence of expressions enclosed in parentheses.
The empty list is either @code{nil} or @code{()}.
``Dotted pairs'' are not allowed.
Anything that is not a list is an @dfn{atom}.

All of these objects may range up to a very large size.
(You may still run into bugs if you make strings or symbols
over about 100 chars in length.)

Comments are enclosed either within @code{#| |#} (which nests properly,
like Common Lisp and unlike C), or else extend from a semicolon
@code{;} to the end of the line.  A comment is equivalent to whitespace,
so @code{(a#|bcd|#e)} is the same as @code{(a e)}, not @code{(ae)}.

@code{#} by itself is a normal token.

True/false values
are just the integers 0 and 1, with no special characteristics.

@deffn GlobalConstant @code{true}
@end deffn
@deffn GlobalConstant @code{false}
These constants are symbolic forms for @code{1} and @code{0}.
They are identical to numbers,
but more descriptive for parameters that are boolean-valued.
@end deffn

Unit, material, and terrain types are distinct objects.
However, they can be considered to have numeric ``indices''
assigned in order of the types' definition.  These numbers
are not directly visible in GDL, but they often affect sorting
and ordering.

You may also supply numbers as @var{dice specs}, which are used in several
tables.  The syntax is the familiar @code{@var{nn}d@var{mm}[+@var{oo}]},
where @var{nn} is the number of dice to throw, @var{mm} is the number of
values on each die, and the optional @var{oo} is an value to be added to
the result.  The die are 0-based, so for instance @code{3d6} yields values
between 0 and 15, while @code{3d6+3} is equivalent to the result of rolling
3 6-sided dice.  The range of each value is severely limited; @var{nn}
may range from 0 to 7, @var{mm} from 0 to 15, and @var{oo} from 0 to 127.
Internally, dice specs are normal integers, in the range 16384 to 32767.

@node Conventions Used, Forms and Evaluation, Lexical Elements, Language Syntax

@subsection Conventions Used

Descriptions of values in this manual follow the conventions listed here.

For parameters described as @var{t/f},
both @code{1}, @code{0} and @code{true}, @code{false} may be used.
Parameters described as @var{n} and @var{n%} are numbers.
Parameters described as @var{dist} or @var{length}
are also numbers, but are in the unit of measure for lengths.
Parameters described as @var{str} or @var{string} are strings.

Parameters described as
@var{u} or @var{ui}, @var{m} or @var{mi}, and @var{t} or @var{ti},
are values that must be unit, material, or terrain types, respectively.

Parameters described as @var{utype-value-list} match unit types with values.
They can have several forms:

@itemize
@item
@code{(n1 n2 ...)} matches @code{n1} with type 0, etc in order.
@item
@code{((u1 n1) (u2 n2) ...)} evaluates @code{u1} to get a unit type,
then matches it with @code{n1}.  @code{u1} etc may also be a list of
types, in which case all the types get matched with @code{n1}.
@end itemize

Other types of lists, such as those defined as @var{side-value-list},
are interpreted similarly.  For all of these, multiple assignments to
the same type etc will overwrite quietly.

List values described as @var{interpolation-list} are lists of pairs
used to derive numerical values by interpolating between the listed
values.  The form of an interpolation list is always
@code{((key1 val1) (key2 val2) ...))}, where @var{keyi} and @var{vali}
are numbers.
If the input value @var{inp} to an interpolation matches @var{keyi}, the result
value is @var{vali}.  If it is between @var{keyi} and @var{keyi+1}, then
the result is gotten by linear interpolation, with the result value falling
somewhere between @var{vali} and @var{vali+1}.
Fractional values always round down.
The @var{keyi} must occur in non-decreasing order; it is
legitimate for two consecutive keys to be identical, in which the result
value will be the value associated with the first key.
If the input value is outside the domain specified by the keys,
the result depends on the particular parameter; some will extrapolate
in some appropriate fashion, while others will generate an error or warning.

Some values may be boolean expressions.  Boolean expressions are lists
headed by the keywords @code{and}, @code{or}, and @code{not}, and may
nest recursively.  For instance, the expression
@example
(and (or false (not false)) true)
@end example
is always true.  In some contexts, values other than @code{true} and
@code{false} may appear, in which case the interpretation of those
values depends on the context.

Some numeric values are @var{stochastic}, meaning that they are partly
fixed and partly probabilistic in effect.  The most common form of this
is values where the part > 100 is divided by 100, while the value mod 100
is the probability to add 1 to the first part.  Thus a value of 425
works out to a value of 4, 3/4 of the time, and to 5, 1/4 of the time,
on average.

@node Forms and Evaluation, Tables, Conventions Used, Language Syntax

@subsection Forms and Evaluation

A @dfn{form} is either any single expression that appears in the file.
A GDL file consists of a sequence of forms.
Most forms of interest will be lists
whose first element is a symbol identifying the form.
For instance, a form beginning with the symbol @code{side}
declares a side object.
When the file containing such a form is read, @i{Xconq} will
create a side object and fill in any properties as specified by the form.
(Properties are like properties or attributes - most GDL objects
have some.)

In most contexts, @i{Xconq} will @dfn{evaluate} an expression
before using it, such as when filling in an object's property.
Numbers and strings evaluate to themselves, while symbols
evaluate to their bindings, as set by @code{set} or @code{define}.
Lists evaluate to a list of the same length, but with all the elements
evaluated, unless the first element of the list is a function.
In that case,
the remaining elements of the list are evaluated and given to the
function, and its result will be the result.

@node Tables, Modifying Objects, Forms and Evaluation, Language Syntax

@subsection Tables

A @dfn{table} is a two-dimensional array of values indexed by types.
Indices can be any pair of unit, material, or terrain type.
The set of tables is fixed by @i{Xconq}, and all are described below.

@deffn Form @code{table} table-name items@dots{}
This is the general form to fill in a table.
The table named by @var{table-name} is filled in from the @var{items}.
If an item is an atom, then every position in the
table is filled in with that item, overwriting any
previously-specified values.
If an item is a list, it must be a three-element list
of the form @code{(@var{type1} @var{type2} @var{value})}.
If both @var{type1} and @var{type2} are single types,
then @var{value} will be put into the table at the position
indexed by the two types.
If one of @var{type1} or @var{type2} evaluates to a list,
@i{Xconq} will iterate over all members of the list while
keeping the other type constant,
while if both @var{type1} and @var{type2} are lists,
then @i{Xconq} will iterate over all pairs from the two lists.
The values used during iteration depend on whether the @var{value}
is a list.  If @var{value} is an atom, then that value will just
be used on every iteration.  If a list, then @i{Xconq} will
use successive elements of the list while iterating.

If the first member of @var{items} is the symbol @code{add},
then the rest of the items will add to the existing contents
of the table rather than clearing to its default value first.
@end deffn

The following forms are all equivalent:
@example
(table foo (a y 1) (b y 2) (c y 3) (a z 9) (b z 9) (c z 9))

(table foo ((a b c) y (1 2 3)) ((a b c) (z) 9))

(define v1 (a b c))
(table foo (v1 y (1 2 3)) (v1 z 9))

(table foo ((a b c) (y z) ((1 2 3) (9 9 9))))

(table foo (a y 1) (b y 2) (c y 3))
(table foo add ((a b c) z 9))
@end example

@node Modifying Objects, Symbols, Tables, Language Syntax

@subsection Modifying Objects

Since forms normally define or create new objects,
GDL defines the @code{add} form to modify existing objects.

@deffn Form @code{add} objects property new-values@dots{}
This form evaluates the atom or list @var{objects} to arrive at the
set of objects to be modified.
Then it uses the @var{new-values} to write new data into
the property named @var{property} of those objects.
The @var{new-values} may be a single number or string, or a list.
@end deffn

@node Symbols, Lists, Modifying Objects, Language Syntax

@subsection Symbols

Most of the symbols used in a game module are the predefined ones
described in this manual.
Others are attached to types when the types are defined,
and still others name objects like units and sides.
You can also define and set your own symbols to arbitrary values.

@deffn Form @code{define} symbol value
This form defines the symbol @var{symbol} to be bound to the
result of evaluating @var{value}.
If @var{symbol} is already defined, @i{Xconq} will issue a warning,
and ignore this form.
@end deffn

@deffn Form @code{set} symbol value
This form rebinds the already-bound symbol @var{symbol}
to be bound to the result of evaluating @var{value}.
If @var{symbol} is @emph{not} bound already,
then @i{Xconq} will issue a warning, but proceed anyway.
@end deffn

@deffn Form @code{undefine} symbol
This form destroys any binding of the @var{symbol}.
This is allowed for any symbol, including already-unbound symbols.
@end deffn

@node Lists,  , Symbols, Language Syntax

@subsection Lists

@deffn Function @code{quote} form@dots{}
This function prevents any evaluation of @var{form}.
(This implies that the abovementioned evaluation of the argument
list does @i{not} happen for this ``function''.)
@end deffn

@deffn Function @code{list} form@dots{}
This function makes a list out of all the @var{form}.
@end deffn

@deffn Function @code{append} form@dots{}
This function appends all the @var{form} (which may be
lists or not) into a single list.  Non-lists will appear
as though they were single-element lists.
@end deffn

@deffn Function @code{remove} list1 list2
This function removes the members of @var{list1} from @var{list2},
returning the result.
@end deffn

@node Game Module Forms, World and Area Forms, Language Syntax, Reference Manual

@section Game Module Forms

The game module declaration supplies information about the file as a whole.
It is optional; if missing, @i{Xconq} will get the module's
name from its file name, and supply defaults for the other properties.

@deffn Form @code{game-module} [ name ] properties@dots{}
This form defines the properties of this game module.
The optional @var{name} is a string that will be used to look up
the module in libraries.
If the @var{name} is supplied, then this form is considered to be the
definition of the module, and overwrites any
@code{game-module} form previously appearing in this file.
If @var{name} is missing, then this form will modify the
existing description of the module.
Although are currently no restrictions enforced on the length or
character set of a module name, @i{Xconq} may warn about a name
that does not match the name of the file containing these forms;
see @xref{Files and Directories} for more detail.
@end deffn

@deffn ModuleProperty @code{title} string
If defined, this property is the name by which the module will be displayed to
players.  It is not used internally, so the name can be modified freely
(unlike the module's name, which may appear in other modules).
Defaults to the module's name.
@end deffn

@deffn ModuleProperty @code{blurb} string
This property is a one-line description that users will see when they
are deciding whether to play the module.
It will be displayed without any modification:
@example
Welcome to my nightmare! (version 1.0 with stronger goblins)
@end example
Defaults to @code{""}.
@end deffn

@deffn ModuleProperty @code{picture-name} string
This property is the name of a picture that may be displayed along
with the module's blurb, by those interfaces that support such pictures.
Defaults to @code{""}.
@end deffn

@deffn ModuleProperty @code{base-game} t/f
@end deffn

@deffn ModuleProperty @code{instructions} strings@dots{}
This property is a list of strings that are the instructions on how to play
the game.  Defaults to @code{()}.
@end deffn

@deffn ModuleProperty @code{notes} strings@dots{}
This property is a list of strings comprising the set of
detailed player's notes for the module.
Both the list and each string in the list can be of any length.
When displayed, the strings are all concatenated together, so the division
into strings here is just for convenience.
How these are displayed is up to the interface, but in general an empty
string signals a new paragraph.
Defaults to @code{()}.
@end deffn

@deffn ModuleProperty @code{design-notes} strings@dots{}
This property is a list of strings that are notes addressed to game designers.
Defaults to @code{()}.
@end deffn

@deffn ModuleProperty @code{version} string
This property is the version of the module.
Defaults to @code{""},
which indicates that the module's version is undefined.
@end deffn

@deffn ModuleProperty @code{program-version} versions
This property dentifies @i{Xconq} versions for which this module
is appropriate.
If specified, then players will get a warning if they attempt to use this
module with an inappropriate version of @i{Xconq}.
Possible forms include a string, which allows the module only for
exactly matching version of @i{Xconq},
and @code{(@var{comparison} @var{version})},
which allows versions satisfying the @var{comparison} test,
which may only be @code{>=} or @code{<=}.
So for instance
@example
(game-module "foo" (program-version (>= "7.0.3")))
@end example
is claimed to only work for versions 7.0.3 or later.
Defaults to @code{""}, which means that the module is appropriate for
any version of @i{Xconq}.

Notes that the @code{program-version} is strictly a heuristic to forewarn
players; in practice it can be very difficult to know which modules work
with which programs.  (The problems are similar to those encountered
by programmers using different compiler versions on their programs.)
@end deffn

@deffn ModuleProperty @code{base-module} name
This property is the name of a module that must be loaded first.
It is similar in effect to @code{include}.
@end deffn

@deffn ModuleProperty @code{default-base-module} name
This property specifies the name of a module that will be loaded
if this module is given as the ``top-level'' module,
such as via @code{-g} on a command line.

This is to prevent disasters when a library module that is
used only by other modules is instead loaded as if it were
a full game design.
@end deffn

@deffn ModuleProperty @code{original-module} name
@end deffn
@deffn ModuleProperty @code{original-version} string
@end deffn
@deffn ModuleProperty @code{original-variants} list
These properties record the module's name, version, and variant selections
before a game save.  They are needed to record the game in the scorefile
usefully.
@end deffn

@menu
* Module Variants::
* Including Other Modules::
* Conditional Loading::
@end menu

@node Module Variants, Including Other Modules, Game Module Forms, Game Module Forms

@subsection Module Variants

Variants are options chosen by players at the start of a game.
A generic variant includes information that will be used for displaying
the choice to players, the acceptable range of choices, a default
choice, and additional forms that may be evaluated if particular
values were chosen.  Variant values are always numbers.

@deffn ModuleProperty @code{variants} items@dots{}
This property defines named variants on this module.
Variants appear as startup options for the game.
The items have the form
@code{([ @var{name} ] @var{type} [ @var{range/default} ] [ @var{clauses} ])}.
The @var{name} is a string or symbol used to identify the choice to
the players, the @var{type} says what sort of change is being enabled,
@var{range/default} supplies a range of values and a default value
among them,
and @var{clauses} is a list of the form @code{(@var{value} @var{forms}@dots{}}.
A game module may specify any number of variants.
Defaults to @code{()}.
@end deffn

A number of commonly useful variant types are predefined.

@deffn VariantType @code{world-size} [ width [ height [ circumf [ lat [ lon ] ] ] ] ] [ clauses ]
This variant allows players to choose the size of the world.
The sizes will default to the values in this variant's data.
(@var{width} and @var{height} can be lists of the form @code{(lo dflt hi)},
with the obvious interpretation??)
@end deffn

@deffn VariantType @code{world-seen} [ dflt ] [ clauses ]
This variant allows players to choose whether
the terrain of the world will be known at the start of the game.
The default setting will be the value @code{dflt},
which may be either @code{true} or @code{false}.
@end deffn

@deffn VariantType @code{see-all} [ dflt ] [ clauses ]
This variant allows players to choose whether everything will be seen
always, as with the global variable @code{see-all}.
The default is set by @code{dflt}.
@end deffn

@deffn VariantType @code{sequential} [ dflt ] [ clauses ]
This variant allows players to choose whether to move
simultaneously during a turn, or one at a time.
The default is set by @var{dflt}.
@end deffn

@deffn VariantType @code{real-time} [ total [ perside [ perturn ] ] ] [ clauses ]
This variant allows players to choose realtime limits on the game.
The value will default to the values in this variant's data.
@c but what about upper/lower limits?
@end deffn

@node Including Other Modules, Conditional Loading, Module Variants, Game Module Forms

@subsection Including Other Modules

You can include one game module in another.

@deffn Form @code{include} module-name [ variant-settings ]
This form has the effect of inserting the contents
of @var{module-name} into the current position in the module.
@code{game-module} forms in the included module are not inserted,
although they are remembered and may appear in displays.
@i{Xconq} will fail completely if the included module cannot be found.

Unlike C etc, the same module cannot be included more than once; you will
get a warning and the module will not be loaded.
@end deffn

Note that the module names are not file names,
so that system-specific features like directories and devices
cannot be included.
The mapping between module name and file name is interface-specific,
so if you want to distribute a module, you should make sure all the
module names don't have anything nonportable embedded.
Alphanumeric characters and hyphens are guaranteed to be portable;
mixed-case names are not.

@node Conditional Loading, , Including Other Modules, Game Module Forms

@subsection Conditional Loading

You can control which forms in a module are actually evaluated
by using conditional loading.

@deffn Form @code{if} test-form sym
@end deffn
@deffn Form @code{else} sym
@end deffn
@deffn Form @code{end-if} sym
If @var{test-form} evaluates to @code{true},
then all subsequent forms, up until the matching @code{else}
or @code{end-if}, will be evaluated.
If @code{false}, then the forms will be read but not evaluated.
All forms inside the conditional must be syntactically correct.
@end deffn

@node World and Area Forms, Side and Player Forms, Game Module Forms, Reference Manual

@section World and Area Forms

The world consists of one @dfn{area},
which is regular in shape and consists of a number of @dfn{cells}.
Each cell has a type of terrain and a number of optional data values.
Each kind of per-cell data will be called a @dfn{layer} of the area.

@deffn Form @code{world} [ circumference ] properties@dots{}
This form defines the properties of the world as a whole.
@end deffn

@deffn Form @code{area} [ width [ height ] ] [ restriction ] properties@dots{}
This form defines the playing area of the world.
The @var{restriction} identifies how to get data for this area from
subsequent forms that are based on larger areas.
@end deffn

@menu
* World Properties::
* Area Properties::
* Layers::
* Distances and Elevations::
* Temperatures::
* Winds::
* Clouds::
@end menu

@node World Properties, Area Properties, World and Area Forms, World and Area Forms

@subsection World Properties

@deffn WorldProperty @code{circumference} dist
This property is the distance around the entire world (as a sphere).
Default is @code{360}.
@end deffn

@deffn WorldProperty @code{axial-tilt} n
This property defines the extremes of seasonal changes.
@end deffn

@node Area Properties, Layers, World Properties, World and Area Forms

@subsection Area Properties

@deffn AreaRestriction @code{restrict} w h x y
This is a special subform that specifies that subsequent layers in an
area of size w x h will be offset by x,y and then read into the
actual area.  (This is useful for setting up a game that needs
only a subset of a full map.)

Note that an area restriction is not a property, and must
always appear before any properties in an area form.
@end deffn

@deffn AreaProperty @code{width} n
@end deffn
@deffn AreaProperty @code{height} n
These properties are the width and height of the world,
as measured in cells.
Allowable values range from 3x3
up to 32767x32767, which is one billion cells!
If only one of these is given, then the other defaults to the same value.
If neither has been given, then they default to @code{60} and @code{30},
respectively.
@end deffn

In the case of a cylinder, the world wraps around
in the x direction, and the width is the diameter of the cylinder,
while the height is just the
height in the usual sense.
A hexagon world is flat on the top and bottom; its width is
measured across the middle height, which is the largest span,
and height is the same
as for cylinders.  Here are some crude pictures, first of an 8x6 cylinder:
@example
# # # # # # # #
 : : + + : : : :
: : : + ^ : : :
 : : : : : : : :
: : : : ^ : : :
 # # # # # # # #
@end example

This world is an 8x7 hexagon:
@example
   # # # # #
  # : + + : #
 # : : + ^ : #
# : : + ^ : : #
 # : : : : : #
  # : : ^ : #
   # # # # #
@end example

There are two kinds of properties that an area may have:
scalar values such as latitude,
and layer values such as terrain and elevation.

@deffn AreaProperty @code{latitude} n
This property is the offset, in cells, from the equator of the middle of the area
(height / 2).
Defaults to @code{0}.
@end deffn

@deffn AreaProperty @code{longitude} n
This property is the offset, in cells, from the ``Greenwich Meridian''
of the world.
Defaults to @code{0}.
@end deffn

@node Layers, Distances and Elevations, Area Properties, World and Area Forms

@subsection Layers

@dfn{Layers} constitute the bulk of data about an area of the world.
Each layer assigns a value to each cell in the area;
examples include cell terrain, temperatures, elevations, and so forth.
Since there may be many cells in a layer with the same values,
each layer uses a common run-length encoding scheme.
In this scheme, each horizontal band of cells
is a separate text string, and the contents of the string encode
individual numeric values, one for each cell.
The encoding uses the characters @code{a..~} and @code{:..[}
for 0 through 63,
and decimal digits followed by commas (or the end of the string)
for all other numbers.
An optional @code{-} is allowed, and indicates a negative value.
Runs of constant value are prefixed with their length, in decimal.
The character @code{*} separates run lengths from values expressed
as digits.
Thus, the string
@example
"40adaa100,2*-99"
@end example
represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100,
and two -99s.
Although this format is quite unreadable,
it has the advantages of compactness and portability;
the expectation is that most layer editing will be done on-line.
Note that the run encoding is entirely optional.

The following subforms at the beginning of layer data have special effects:

@deffn LayerSubform @code{constant} n
This subform causes every value in the layer to be set to @var{n}.
@end deffn

@deffn LayerSubform @code{subarea} x y w h
This subform indicates that the layer data should be positioned at the given
rectangle in the layer.
@end deffn

@deffn LayerSubform @code{xform} mul add
This subform has the effect of first multiplying the raw value by @var{mul},
then adding @var{add} and storing the result into the layer.
@end deffn

@deffn LayerSubform @code{by-bits}
@end deffn

@deffn LayerSubform @code{by-char} str
This subform specifies that the characters in @var{str} give the
encodings of values in the layer.
The first character in @var{str} encodes 0, the second encodes 1,
and so forth.
@end deffn

@deffn LayerSubform @code{by-name} name-list
[what is the syntax of name-list exactly?]
This subform is for generic worlds that are useful across multiple game designs.
It has the syntax @code{((sym1 n1) (sym2 n2) ...)}, where @var{symi} is
either a symbol or number that is the real value in the layer, and @var{ni}
is the value used in the layer's encoding.
For example, in the terrain layer,
this allows for the matching of terrain types by name,
so that if, say,
the ``sea'' terrain type was type #0 in one game and type #4 in another,
the world would have sea in all the same places after it was read in.
In practice, only a few worlds are this general.
If a value appears in the layer's data that is not listed,
that value will simply go into the layer verbatim.
@end deffn

@deffn AreaProperty @code{terrain} layer-data@dots{}
This property is the actual layer of terrain types for cells.
@end deffn

@deffn AreaProperty @code{aux-terrain} terrain-type layer-data@dots{}
This property fills in values for borders, connections, and coatings.
For border and connection terrain,
the value is a six-bit number (0..63),
with a bit turned on in each direction that there is a border
or connection.
For coating types, the value is the depth of the coating.
@end deffn

@deffn AreaProperty @code{features} feature-list layer-data@dots{}
This property specifies the nature and location of all geographical features.
The @var{feature-list} is a list of lists, where each sublist has the form
@code{([@var{id}] @var{typename} @var{name} [@var{super}])}
where @var{id} is the numerical id referenced in the layer data
(defaults to feature's position in the @var{feature-list}),
@var{typename} is a symbol or string giving the general type of feature
(such as @code{bay}),
@var{name} is the name of the feature
(such as @code{"Bay of Bengal"}),
and @var{super} is the optional id of another feature that
incorporates this feature.
@end deffn

@deffn AreaProperty @code{material} material-type layer-data@dots{}
This property declares the quantity of the given @var{material-type}
in each cell of the area.
@end deffn

@deffn AreaProperty @code{people-sides} layer-data@dots{}
This property says which side the people of each cell are on.
A @var{side-encoding} of @code{exact} assigns 0 to independence (no side),
1 to the first side, and so forth; otherwise, the encoding is a list
of side names/ids and numbers.
@end deffn

@node Distances and Elevations, Temperatures, Layers, World and Area Forms

@subsection Distances and Elevations

@deffn AreaProperty @code{elevations} layer-data@dots{}
This property is the world elevation data itself.
If any elevation falls outside the min/max elevation range
for the terrain type of the cell, then it
will be truncated appropriately.
Defaults to @code{0} for each cell.
@end deffn

@deffn AreaProperty @code{cell-width} dist
This property is the distance across a single cell,
expressed as units of elevation.  Defaults to @code{1}.
@end deffn

@node Temperatures, Winds, Distances and Elevations, World and Area Forms

@subsection Temperatures

Each type of terrain has a temperature range in which it may be found.
Any calculation that would fall outside this range will be clipped.

The temperature can be set to have a given value at a given elevation.
All air temperatures will be interpolated appropriately.

@deffn GlobalVariable @code{temperature-floor} n
This variable is the lowest possible temperature.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{temperature-floor-elevation} n
This variable is the elevation at which the temperature is always at
@code{temperature-floor}.
Defaults to @code{0}.
@end deffn

@deffn AreaProperty @code{temperatures} layer-data@dots{}
This property contains the temperature data itself.
If any temperature falls outside the min/max temperature range, then it
will be truncated appropriately.
Defaults to @code{0} for each cell.
@end deffn

@node Winds, Clouds, Temperatures, World and Area Forms

@subsection Winds

Winds are defined as having a nonnegative force and a direction.

@deffn AreaProperty @code{winds} layer-data@dots{}
This property contains the force and direction of the prevailing
winds in each cell.
@end deffn

@node Clouds,  , Winds, World and Area Forms

@subsection Clouds

Cloud cover is defined as a layer over the terrain, with
a bottom and top and density for each cell.

@deffn AreaProperty @code{clouds} layer-data@dots{}
This property is the degree of cloud cover over each cell.
A value of @code{0} corresponds to clear skies.
@end deffn

@deffn AreaProperty @code{cloud-bottoms} layer-data@dots{}
This property is the altitude above the ground of the bottoms
of the clouds.
@end deffn

@deffn AreaProperty @code{cloud-heights} layer-data@dots{}
This property is the vertical thickness of the cloud cover
in each cell.
@end deffn

@node Side and Player Forms, Unit Forms, World and Area Forms, Reference Manual

@section Side and Player Forms

@deffn Form @code{side} [ id ] properties@dots{}
This form has the effect of declaring a side to exist.
If the number or symbol @var{id} is supplied and
matches that of a side that has already been created,
then the properties will modify the pre-existing side.
Otherwise a new side object will be created,
with a arbitrarily-chosen numeric id ranging between 1 and @code{sides-max}.
If the given @var{id} is a symbol, then the side's numeric id will be
bound to that symbol.
@end deffn

@deffn GlobalVariable @code{sides-min} n
@end deffn
@deffn GlobalVariable @code{sides-max} n
These variables are the minimum and maximum number of sides that may exist in
a game.  Defaults are to @code{1} and the internal parameter @code{MAXSIDES},
which is usually around 7.
@code{MAXSIDES} can only be changed by recompiling @i{Xconq}.
@end deffn

@deffn Form @code{side-defaults} properties@dots{}
This form sets the defaults for all newly-created sides declared
subsequently.
These defaults will be set before the new side's properties are interpreted.
This form has no effect on existing sides or on side declarations that
modify existing sides.
@end deffn

@menu
* Side Name Properties::
* Side Class::
* Status in Game::
* Side Relationships::
* Numbering Units::
* Side-Specific Namers::
* Side Tech Levels::
* Side Views::
* Interaction::
* Doctrine::
* Other::
* Players::
* Rules of Side Configuration::
@end menu

@node Side Name Properties, Side Class, Side and Player Forms, Side and Player Forms

@subsection Side Name Properties

If the game design allows, all of these properties can be set at startup by
the players (see <side config> and below).
Omission of some of these results in suppression or substitution,
depending on the interface and the situation.
Omission of all name properties allows the side to go unmentioned,
which is useful when the concept of ``side'' is useless or
confusing to a player (as in some adventure games).
All of these properties may be set at any time by any player.

@deffn SideProperty @code{name} str
This property is the proper name of a side, as a country or alliance name.
Examples include @code{"Axis"} and @code{"Hyperborea"}.
Defaults to @code{""}.
@end deffn

@deffn SideProperty @code{long-name} str
This property is the long form of a side's name,
as in @code{"People's Republic of Hyperborea"}.
Defaults to be the same as the side's name.
@end deffn

@deffn SideProperty @code{short-name} str
This property is an short name or acronym for the side,
often just the letters of the long name, as in @code{"PRH"}.
Defaults to @code{""}.
@end deffn

@deffn SideProperty @code{noun} str
This property is the name of an individual unit or person
belonging to the side.
Defaults to @code{""}, which suppresses any mention of the side
when (textually) describing the individual.
@end deffn

@deffn SideProperty @code{plural-noun} str
This property is what you would call a group of individuals.
Defaults to the most common plural form of the @code{noun}
(in English, the default pluralizer adds an ``s''),
so any alternative plural noun, such as @code{"Chinese"},
will need an explicit @code{plural-noun} value.
@end deffn

@deffn SideProperty @code{adjective} str
This property is an adjective that can be used of individuals on the side,
as in @code{"Spanish"}.
Defaults to @code{""}, which suppresses use of the adjective.
@end deffn

As a complete example, a side named @code{"Poland"} would have a long name
@code{"Kingdom of Poland"}, short name @code{"Po"},
noun @code{"Pole"}, plural noun @code{"Poles"},
and adjective @code{"Polish"}.

@deffn SideProperty @code{color} str
This property is a comma-separated list of colors that represents the side.
Defaults to @code{"black"}.
@end deffn

@deffn SideProperty @code{emblem-name} str
This property is the name of a graphical icon that represents the side.
An emblem name of @code{"none"} suppresses any emblem display for the side.
Defaults to @code{""}, which gives the side a randomly-selected emblem.
@end deffn

@deffn SideProperty @code{names-locked} t/f
If the value of this property is @code{true},
then the player cannot modify any of the side's names.
Defaults to @code{false}.
@end deffn

@node Side Class, Status in Game, Side Name Properties, Side and Player Forms

@subsection Side Class

@deffn SideProperty @code{class} str
This property is a side's class, which is a keyword that characterizes the side.
Any number of sides may be in the same class.
Defaults to @code{""}.
@end deffn

@node Status in Game, Side Relationships, Side Class, Side and Player Forms

@subsection Status in Game

Once a side is in the game, it can never be totally removed.
However, sides can become inactive.

@deffn SideProperty @code{active} t/f
This property is @code{true} if the side is still actively participating in the game.
If the side has won, lost, or simply withdrew, this will be @code{false}.
Any units on a side not in the game are effectively frozen statues;
they don't do anything, and are untouchable by anyone else.
Defaults to @code{true}.
@end deffn

@deffn SideProperty @code{status} lose/draw/win
This property tells how this side did in the game.  Defaults to @code{draw}.
@end deffn

@deffn GlobalConstant @code{win}
@end deffn
@deffn GlobalConstant @code{draw}
@end deffn
@deffn GlobalConstant @code{lose}
These constants are the different possible values for a side's status.
@end deffn

@deffn SideProperty @code{ever-active} t/f
This property records if the side was ever active during the course of a game.
Sides that were never active (perhaps because they are used in some scenarios
of a game design but not others) will not be recorded in the scorefile.
@end deffn

@deffn SideProperty @code{advantage} n
@end deffn
@deffn SideProperty @code{advantage-min} n
@end deffn
@deffn SideProperty @code{advantage-max} n
Initial and min/max limits on advantage for the side.
All default to the values of the corresponding global variables.
@end deffn

@node Side Relationships, Numbering Units, Status in Game, Side and Player Forms

@subsection Side Relationships

By default, sides are neutral with respect to each other.

Control is a situation where one side
can observe and move another side's units, but not vice versa.
The controlling side can also just take the units of the controlled side.
If the controlled side loses or resigns, then the controlling side
automatically gets everything.
Both sides must agree to this relationship.

@deffn SideProperty @code{controlled-by} side
This property refers to the side controlling this one.
If 0, then the side is not under control.
Defaults to @code{0}.
@end deffn

The closest side relationship is one of trust.
A trusted side unit's may do anything at any time,
including entering and leaving units on the other side,
consuming the other side's materials, and so forth.

@deffn SideProperty @code{trusts} side-value-list
This property is true for any side that is trusted by this side.
Note that this relationship need not be symmetrical.
Defaults to @code{false} for all sides.
@end deffn

Note that these parameters apply only to relationships as enforced by
@i{Xconq}.  In an actual game, both human and robot sides can make agreements
and have positive/negative opinions about the other sides.

@deffn SideProperty @code{trades} side-value-list
This property defines the trading relationship with other sides.
Defaults to @code{0} for all sides.
@end deffn

@node Numbering Units, Side-Specific Namers, Side Relationships, Side and Player Forms

@subsection Numbering Units

@deffn SideProperty @code{next-numbers} utype-value-list
This property gives the next serial numbers that will be assigned to units
acquired by this side.
Defaults to @code{1} for each unit type (Dijkstra notwithstanding,
that's still where people start numbering things).
@end deffn

If the unit is of a type that gets numbered
(@code{assign-number} property is true),
then any unit of that type, acquired by any means whatsoever,
will be assigned the @code{next-numbers} value for that type
and @code{next-numbers} will be incremented.

@node Side-Specific Namers, Side Tech Levels, Numbering Units, Side and Player Forms

@subsection Side-Specific Namers

A side can have its own set of namers (see below)
that will be used for units
and geographical features associated with that side.

@deffn SideProperty @code{unit-namers} utype-value-list
This property specifies which namers will be used with which types
that the side starts out with or creates new units.
These will not be run automatically on captured units or gifts.
Defaults to @code{""} for each unit type.
@end deffn

@deffn SideProperty @code{feature-namers} feature-type-value-list
This property specifies which namers to use with which geographical
features in the side's initial country (if if has one).
Defaults to @code{()}.
@end deffn

@node Side Tech Levels, Side Views, Side-Specific Namers, Side and Player Forms

@subsection Side Tech Levels

The tech level of a side determines what it can do with each type of unit.

@deffn SideProperty @code{tech} utype-value-list
This property assigns a tech level to each unit type named.
Defaults to @code{0} for each unit type.
@end deffn

@deffn SideProperty @code{init-tech} utype-value-list
This property is the tech level at the beginning of the current turn.
Defaults to @code{0} for each unit type.
@end deffn

@node Side Views, Interaction, Side Tech Levels, Side and Player Forms

@subsection Side Views

These properties are necessary only if the relevant globals
are set a certain way (@code{see-all} is false, etc).

@deffn SideProperty @code{terrain-view} layer-data@dots{}
This property is the side's current knowledge of the world's terrain.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{terrain-view-dates} layer-data@dots{}
This property is the dates of the side's current knowledge of the
world's terrain.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{aux-terrain-view} ttype layer-data@dots{}
This property is the side's current knowledge of the world's aux terrain
of type @var{ttype}.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{aux-terrain-view-dates} ttype layer-data@dots{}
This property is the dates of the side's current knowledge of the
world's aux terrain of type @var{ttype}.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{unit-view} layer-data@dots{}
This property is the side's current knowledge of the world.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{unit-view-dates} layer-data@dots{}
This property is the turn number at which the unit view data
in the corresponding cell of the @code{unit-view} was set.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{material-view} mtype layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{material-view-dates} ttype layer-data@dots{}
Defaults to @code{()}.
@end deffn

If the weather is not always known and up-to-date, then the
following properties what is known and when the information
was recorded.

@deffn SideProperty @code{temperature-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{temperature-view-dates} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-bottom-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-height-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{cloud-view-dates} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{wind-view} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{wind-view-dates} layer-data@dots{}
Defaults to @code{()}.
@end deffn

@node Interaction, Doctrine, Side Views, Side and Player Forms

@subsection Interaction

@deffn SideProperty @code{turn-time-used} seconds
This property is the number of (real) seconds
that this side has been moving units during the present turn.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{total-time-used} seconds
This property is the number of (real) seconds that
this side has been moving units during the course of the game.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{timeouts} n
This property is the number of ``time outs'' a side gets for the game.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{timeouts-used} n
This property is the number of ``time outs'' a side has already used up.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{finished-turn} t/f
This property is true if the side has declared that it is finished moving
things during this turn.
Defaults to @code{false}.
@end deffn

@deffn SideProperty @code{willing-to-draw} t/f
This property is true if the side will go along
with any other side that wants to end the game in a draw.
Defaults to @code{false}.
@end deffn

@node Doctrine, Other, Interaction, Side and Player Forms

@subsection Doctrine

Doctrines are objects that units consult to decide about individual behavior.

@deffn SideProperty @code{doctrines} utype-property-groups@dots{}
This property is the side's unit-type-specific doctrine.
Each @var{utype-property-group} has the form
@code{(@var{unit-types} doctrine)}.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{doctrines-locked} t/f
This property says whether the docrine-unit type correspondence
for the side may be altered during the game.
This property does not control whether or not the properties
of the doctrines may be altered.
Defaults to @code{false}.
@end deffn

@deffn SideProperty @code{default-doctrine} doctrine-id
This property is the base doctrine that applies to all unit types
by default.
Defaults to @code{0}.
@end deffn

@deffn Form @code{doctrine} [ id ] properties@dots{}
This form creates a doctrine with the given id and properties.
@end deffn

@deffn DoctrineProperty @code{ever-ask-side} t/f
This property is the true if the unit may ask the player for what to do,
instead of picking some default activity.
@end deffn

@deffn DoctrineProperty @code{construction-run} type-value-list
This property is the default number of units to build when
construction has been requested.
@end deffn

@deffn DoctrineProperty @code{locked} t/f
This property is true if the properties of the doctrine
cannot be modified by the side's player during the game.
Defaults to @code{false}.
@end deffn

@node Other, Players, Doctrine, Side and Player Forms

@subsection Other

@deffn SideProperty @code{self-unit} unit
This property identifies a unit that represents the side itself.
The value may be a unit id, number, string, or symbol.
Defaults to @code{0}, which means that no unit represents the side.
See below for more details on self units.
@end deffn

@deffn SideProperty @code{priority} n
The order in which the side will get to act, relative to other sides
and to units.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{scores} (skid val)@dots{}
This property is the current values of any numeric scores being
kept for the side.  It is a list of pairs of scorekeeper id and value.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{attack-stats} n@dots{}
@end deffn
@deffn SideProperty @code{hit-stats} n@dots{}
These properties are the raw counts of attacks and hits, by attacking
and defending unit types.
Default to @code{}.
@end deffn

@deffn SideProperty @code{gain-counts} n@dots{}
@end deffn
@deffn SideProperty @code{loss-counts} n@dots{}
These properties are the raw counts of unit gains and losses,
organized by unit type and gain/loss reason.
Default to @code{0}.
@end deffn

@deffn Form @code{independent-units} properties@dots{}
Like the @code{side} form, but sets properties for independent units.
@end deffn

@deffn SideProperty @code{ui-data} data@dots{}
This property contains interface-specific data for the side.
This is mainly for preservation across game save/restores.
The property's value has the form
@code{((interface-type data) (interface-type data) ...)},
so that each interface can maintain its own data separately.
@end deffn

@deffn SideProperty @code{ai-data} data@dots{}
This property is information about the AIs associated with a side.
The property's value has the form
@code{((ai-type data) (ai-type data) ...)},
so that each type of AI can maintain its own data separately.
The form and meaning of each AI's data is specific to it alone.
Defaults to @code{()}.
@end deffn

@node Players, Rules of Side Configuration, Other, Side and Player Forms

@subsection Players

Player objects are rarely necessary when building game designs;
they typically only appear in saved games,
in order to ensure that the same players get the same sides
upon restoration.

@deffn SideProperty @code{player} id
This property is the unique identifier of a player that is running this side.
Defaults to @code{0}, which means that no player has been assigned
to the side.
@end deffn

@deffn Form @code{player} [ id ] properties@dots{}
This form defines a player.
If the @var{id} is supplied and matches the id of an existing player,
then the player object is updated using the @var{properties},
otherwise a new player object will be created,
using the given @var{id} if supplied, otherwise creating a new value.
@end deffn

@deffn GlobalVariable @code{player-sides-locked} t/f
This variable is @code{true} if the player/side assignment may not
be changed while the game is starting up.
Defaults to @code{false}.
@end deffn

The number of players must always be less than the number of sides
(sides without players just don't do anything).

@deffn PlayerProperty @code{name} str
This property identifies the player by name.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{config-name} str
This property identifies a particular set of doctrine and other definitions
that the player is using.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{display-name} str
This property identifies the display being used by the player's interface.
The interpretation of this value is dependent on the interface in use.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{ai-type-name} str
This property is the type of AI that will play the side
if requested or necessary.
The set of choices depends on what has been compiled into @i{Xconq}.
(The general-purpose AI type @code{"mplayer"} will usually be available,
but is not guaranteed.)
An @code{ai-type-name} of @code{""} means that no AI will run this player.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{password} str
This property is the encoding of a password that must be entered before this
player object can be reused successfully.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{initial-advantage} n
This property is an initial relative strength at which the player should start.
Some synthesis methods can use this to give more units or some other
advantage to each player according to the requested strength.
Defaults to @code{1}.
@end deffn

@deffn GlobalVariable @code{advantage-min} n
@end deffn
@deffn GlobalVariable @code{advantage-max} n
@end deffn
@deffn GlobalVariable @code{advantage-default} n
These variables set the bounds and default values for players'
initial advantages.
Default to @code{1}, @code{9999}, and @code{1}, respectively.
@end deffn

@i{Xconq} is not guaranteed to be able to be able to set up a game
with any combination of player advantages;
the limits depend on the capabilities and characteristics of the
synthesis methods that use the requested advantages in their
calculations.

@node Rules of Side Configuration,  , Players , Side and Player Forms

@subsection Rules of Side Configuration

The properties of a side can come from a number of different sources
(here listed in order of precedence):

@itemize

@item
Interface-specific sources (X resources, Mac preferences).

@item
Game-specific form in player's configuration file.

@item
Generic form in player's configuration file.

@item
The @code{side} form for the side.

@item
The @code{side-defaults} form for the game.

@item
General program defaults.
@end itemize

Note that interface-specific and general config files can never alter
certain properties of a side, and can only alter others if they are
not locked.

@node Unit Forms, Agreements, Side and Player Forms, Reference Manual

@section Unit Forms

The basic @code{unit} form creates or modifies a unit.

@deffn Form @code{unit} id [ type ] properties@dots{}
This form defines a unit.
If a numeric @var{id} is supplied and matches the id of an existing unit,
then that unit will be modified by @var{properties},
and the optional @var{type} will be interpreted as a new type for the unit.
Otherwise a new unit will be created,
with either @var{id} as its id or
a arbitrarily-selected one if @var{id} is already in use.
If the unit's id is newly-generated and no type has been specified,
then type #0 (first-defined type) will be the type of the unit.
An id of @code{0} can never match an existing unit id, so effect
will be as if it had been omitted.
@end deffn

@deffn Form @var{unit-type-name} x y [ side-id ] properties@dots{}
This is an abbreviated form, in which
the x,y position is required, and an optional side id may be included.
The side id will come from @code{unit-defaults} if not specified.
The @var{unit-type-name} may be any valid unit type name or
defined name.
This form always results in a new unit.
@end deffn

Since there may be many units whose properties are similar, there
is a ``default unit'' whose properties fill in missing properties in
individual unit declarations.

@deffn Form @code{unit-defaults} [ modifier ] properties@dots{}
This form sets the default values for all subsequent units read in,
in this and every other module not yet loaded.
The set of defaults is additive,
so for instance you can repeatedly change the default side of units.
If the symbol @code{reset} has been supplied for the optional @var{modifier},
then all the defaults will be changed to the basic default
values, as described in this manual.
@end deffn

@deffn Symbol @code{reset}
This is the symbol used to reset unit defaults; see above.
@end deffn

@menu
* Unit Properties::
* Unit Action State::
* Unit Plan::
* Goal Types::
* Task Types::
@end menu

@node Unit Properties, Unit Action State, Unit Forms, Unit Forms

@subsection Unit Properties

This section lists properties of individual units.
In general, they default to the most common or reasonable values,
so need not always be specified, even in a saved game.

@deffn UnitProperty @code{@@} x y [ z ]
This property is the position of the unit.
Defaults to @code{-1,-1,0}, which causes the unit to be placed randomly.
The optional altitude @var{z} can also be set separately with
the property @code{z} below.
If @i{z} is even and the unit is in the open,
then the unit's altitude is @i{z/2};
if @i{z} is odd, then @i{(z-1)/2} is the type of connection terrain
that the unit is on.
@end deffn

@deffn UnitProperty @code{z} z
This property is identical to the optional z part of the @code{@@} property.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{s} side
This property is the side of the unit.
It can be either a side name/noun/adjective (string) or id (number).
A value of @code{0} or @code{"independent"}
means that the unit is independent.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{os} side
This property is the original side of the unit.
It can be either a side name/noun/adjective (string) or id (number).
A value of @code{0} or @code{"independent"}
means that the unit is/was originally independent.
Defaults to the unit's actual side when first read in or created.
@end deffn

@deffn UnitProperty @code{#} n
This property is the unique numeric id of the unit.
Defaults to a game-selected value.
@end deffn

@deffn UnitProperty @code{n} str
This property is the name of the unit.
Defaults to @code{""}.
@end deffn

@deffn UnitProperty @code{nb} n
This property is the number of the unit,
which starts at @code{1} and goes up.
Defaults to @code{0}, which means that the unit is unnumbered.
@end deffn

@deffn UnitProperty @code{cp} n
This property is the current completeness of the unit.
If negative, indicates that the unit will appear at a time
and place specified by the @code{appear} x-property.
Defaults to the @code{cp-max} for the type.
@end deffn

@deffn UnitProperty @code{hp} n
This property is the current hit points of the unit.
Will be restricted to the range [0, hp-max].
An hp of 0 means that the unit is dead and will not appear in the game.
Defaults to @code{hp-max} for the unit's type.
@end deffn

@deffn UnitProperty @code{cxp} cxp
This property is the combat experience of the unit.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{mo} n
This property is the morale of the unit.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{m} mtype-value-list
This property is the amounts of supplies being carried by the unit.
Defaults to @code{0} for each material type.
@end deffn

@deffn UnitProperty @code{tp} utype-value-list
This property is the level of tooling to build each type of unit.
Defaults to @code{0} for each unit type.
@end deffn

@deffn UnitProperty @code{in} n
This property is the id of the unit's transport.
Defaults to @code{0}, meaning that unit is not in any transport.
@end deffn

@deffn UnitProperty @code{opinions} side-value-list@dots{}
This property is the unit's true feelings towards each side,
including its own side.
Defaults to @code{0} for each side.
@end deffn

@deffn UnitProperty @code{appear} n
This property is the turn on which a unit will appear.
The unit's cp must also be negative, and its position must be
negatives of its position.
Defaults to @code{-1}.
@end deffn

@deffn UnitProperty @code{disappear} n
This property is the turn on which a unit will disappear from
the game.  Occupants will be ejected if possible; otherwise
they will disappear also.
Defaults to @code{-1}.
@end deffn

@deffn UnitProperty @code{x} obj
This property is the optional extension properties of the unit.
Its value may be any object.
Defaults to @code{()}.
@end deffn

@node Unit Action State, Unit Plan, Unit Properties, Unit Forms

@subsection Unit Action State

@deffn UnitProperty @code{act} subprops
This property specifies the current action state of the unit.
@end deffn

@deffn UnitActionStateProperty @code{acp} n
This property is the number of action points left to the unit for this turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{acp0} n
This property is the initial number of action points for this turn,
computed at the beginning of the turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{aa} n
This property is the actual number of actions executed by the
unit so far in the current turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{am} n
This property is the actual number of moves (cell entries)
executed so far in the current turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{a} action
This property is the next action that the unit will perform.
@end deffn

Note that if any unit-defining form has an @code{act} property,
@i{Xconq} will start at an appropriate point in the middle of a turn,
giving all other units zero acp and mp,
rather than starting at the beginning of the turn
and computing acp and mp for all units.

@node Unit Plan, Goal Types, Unit Action State, Unit Forms

@subsection Unit Plan

@deffn UnitProperty @code{plan} type [ creation-turn ] properties@dots{}
This property describes the unit's current plan.
@end deffn

@deffn PlanType @code{none}
A unit with this type of plan does nothing.
It is used when a side has no player.
@end deffn

@deffn PlanType @code{passive}
This plan type is for units on a side that is being run directly
by the side.
@end deffn

@deffn PlanType @code{defensive}
This plan type is for units that defend areas or other units.
@end deffn

@deffn PlanType @code{offensive}
This plan type is for units that are to be aggressive.
@end deffn

@deffn PlanType @code{exploratory}
This plan type is for units that explore the world.
@end deffn

@deffn PlanType @code{random}
A unit with this plan type will act randomly.
@end deffn

@deffn PlanProperty @code{goal} goal
This property is the main goal of a unit's plan.
Defaults to @code{()}.
@end deffn

@deffn PlanProperty @code{formation} goal
This property is the formation goal of a unit's plan.
If defined, it is a position goal that the unit should
try to achieve when it is not trying to achieve the main goal.
Defaults to @code{()}.
@end deffn

@deffn PlanProperty @code{tasks} tasks@dots{}
This property is the complete task agenda for the unit's plan.
It is a list of tasks.
Defaults to @code{()}.
@end deffn

@deffn PlanProperty @code{asleep} t/f
This property is true if the unit is asleep.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{reserve} t/f
This property is true if the unit is in reserve.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{delayed} t/f
This property is true if the unit's activity
has been delayed until all others have acted.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{wait} t/f
This property is true if the unit is waiting for orders.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{ai-control} t/f
This property is true if the unit can be controlled by
any AI associated with the side.
Defaults to @code{true}.
@end deffn

@deffn PlanProperty @code{supply-alarm} t/f
This property is true if the unit should react when supply
is low.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{supply-is-low} t/f
This property is true if the unit considers its supply
to be low.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{wait-transport} t/f
This property is true if the unit is waiting for transport.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{initial-turn} turn
This property is the turn upon which a plan should go into effect.
Defaults to @code{0}.
@end deffn

@deffn PlanProperty @code{final-turn} turn
This property is the turn upon which a plan should be removed.
If the value is @code{0}, then the plan is not scheduled to
be removed.
Defaults to @code{0}.
@end deffn

@node Goal Types, Task Types, Unit Plan, Unit Forms

@subsection Goal Types

The possible types of goals are these:

@deffn GoalType @code{no-goal}
@end deffn

@deffn GoalType @code{won-game}
@end deffn

@deffn GoalType @code{lost-game}
@end deffn

@deffn GoalType @code{world-is-known}
@end deffn

@deffn GoalType @code{vicinity-is-known}
@end deffn

@deffn GoalType @code{positions-known}
@end deffn

@deffn GoalType @code{cell-is-occupied}
@end deffn

@deffn GoalType @code{vicinity-is-held}
@end deffn

@deffn GoalType @code{has-unit-type}
@end deffn

@deffn GoalType @code{has-unit-type-near}
@end deffn

@deffn GoalType @code{has-material-type}
@end deffn

@deffn GoalType @code{keep-formation}
@end deffn

@node Task Types,  , Goal Types, Unit Forms

@subsection Task Types

This section lists all the types of tasks that a unit may
perform.  Every task includes the two parameters @var{ex}
and @var{re}; the first is a record of how many times the
task has been executed, and the second records how many
times the task has failed.  (@i{Xconq} will retry a failed
task several times before abandoning it.)

@deffn TaskType @code{build} ex re u n n2 unit-id
This type of task directs the unit to build @var{n} units
of type @var{u}.  @var{n2} is the number already built
in the run and @var{unit-id} is the (optional) id of a
unit already being built.
@end deffn

@deffn TaskType @code{capture} ex re unit-id
@end deffn

@deffn TaskType @code{disband} ex re
This type of task directs the unit to disband itself.
@end deffn

@deffn TaskType @code{do-action} ex re n action
@end deffn

@deffn TaskType @code{hit-position} ex re x y z
This type of task directs the unit to attack or fire on
any unfriendly units at the given location.
@end deffn

@deffn TaskType @code{hit-unit} ex re unit-id
@end deffn

@deffn TaskType @code{move-dir} ex re dir n
This type of task directs the unit to move in direction
@var{dir} for a distance of @var{n} cells.
@end deffn

@deffn TaskType @code{move-to} ex re x y z dist
This type of task directs the unit to move to a distance of
no more than @var{dist} cells from the given location.
@end deffn

@deffn TaskType @code{occupy} ex re unit-id
This type of task directs the unit to attempt to enter
the given @var{unit-id}, moving adjacent to it first
if necessary.
@end deffn

@deffn TaskType @code{pickup} ex re unit-id
This type of task directs the unit to move towards
the given @var{unit-id}.
@end deffn

@deffn TaskType @code{repair} ex re unit-id
@end deffn

@deffn TaskType @code{resupply} ex re
This type of task directs the unit to replenish its supplies,
whether by doing more production or by moving to another
unit that has supplies available.
@end deffn

@deffn TaskType @code{sentry} ex re n
This task type directs the unit to stay where it is for
the next @var{n} turns.
@end deffn

@node Agreements, Scorekeeper Forms, Unit Forms, Reference Manual

@section Agreements

@deffn Form @code{agreement} [ id ] properties@dots{}
This form defines an agreement among a set of sides.
The name/id is a unique internal identifier.
@end deffn

@deffn AgreementProperty @code{type-name} str
This property is the name of the general type of agreement,
such a trade.
Defaults to @code{""}.
@end deffn

@deffn AgreementProperty @code{title} str
This property is the player-visible name of the agreement.
Defaults to @code{""}.
@end deffn

@deffn AgreementProperty @code{terms} forms@dots{}
This property is the list of terms of the agreement.
Defaults to @code{()}.
@end deffn

@deffn AgreementProperty @code{drafters} side-list
This property is the set of sides writing the agreement.
Only drafting sides may modify an agreement.
@end deffn

@deffn AgreementProperty @code{proposers} side-list
This property is the set of sides that initially proposed the agreement.
@end deffn

@deffn AgreementProperty @code{signers} side-list
Before the agreement is made,
this property is the proposed list of participants.
After the agreeement is made,
this is the actual list of participants.
@end deffn

@deffn AgreementProperty @code{willing-to-sign} side-list
This property is all the sides that have already agreed to this agreement,
on condition that all the other sides accept it.
@end deffn

@deffn AgreementProperty @code{known-to} side-list
This property is the set of sides that are to know about the
agreement when it is signed.
@end deffn

@deffn AgreementProperty @code{enforcement} form
@end deffn

@deffn AgreementProperty @code{state} state
@end deffn

@node Scorekeeper Forms, History Forms, Agreements, Reference Manual

@section Scorekeeper Forms

Scorekeepers are the objects that manage scoring, winning, and losing.
A game design need not define any scorekeepers,
and none are created by default.
A scorekeeper may either maintain a numeric score that is used at
the end of the game to decide rankings, or simply declare a side
to have won or lost.

@deffn Form @code{scorekeeper} name properties@dots{}
This form creates or modifies a scorekeeper with the given @var{name},
with the given @var{properties}.
@end deffn

@menu
* Scorekeeper Properties::
* Scorekeeper Bodies::
* Scorekeeper Functions::
* Scorefile::
@end menu

@node Scorekeeper Properties, Scorekeeper Bodies, , Scorekeeper Forms

@subsection Scorekeeper Properties

@deffn ScorekeeperProperty @code{title} str
This property is a string that identifies the scorekeeper to the players.
Defaults to @code{""}.
@end deffn

@deffn ScorekeeperProperty @code{when} (type [ exp ])
This property is when the scorekeeper will be checked or updated.
Defaults to @code{after-turn}.
@end deffn

@deffn ScorekeeperWhenType @code{before-turn} exp
This indicates that the scorekeeper will run at the start of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.
@end deffn

@deffn ScorekeeperWhenType @code{after-turn} exp
This indicates that the scorekeeper will run at the end of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.
@end deffn

@deffn ScorekeeperWhenType @code{after-event} exp
This indicates that the scorekeeper will run after every event
matching @var{exp}, or after every event if @var{exp} is not given.
@end deffn

@deffn ScorekeeperWhenType @code{after-action} exp
This indicates that the scorekeeper will run at the end of each action
matching @var{exp}, or after every action if @var{exp} is not given.
@end deffn

@deffn ScorekeeperProperty @code{applies-to} side-list
This property is the set of sides or side classes
to which the scorekeeper applies.
Scorekeepers apply only to sides that are in the game.
Defaults to @code{side*}.
@end deffn

@deffn ScorekeeperProperty @code{known-to} side-list
This property is the list of sides that know about this scorekeeper,
and can see the value of the score for each side that it applies to.
Defaults to @code{side*}.
@end deffn

@deffn ScorekeeperProperty @code{trigger} form
This property is an expression that is true when it is time
to start checking the scorekeeper's main test.
Once a scorekeeper is triggered, it remains active.
Defaults to @code{false}.
@end deffn

@deffn ScorekeeperProperty @code{triggered} t/f
This property is true if the scorekeeper is currently triggered.
Defaults to @code{true}.
@end deffn

@deffn ScorekeeperProperty @code{do} forms@dots{}
This property is a list of forms to execute in order
each time the scorekeeper runs.
Defaults to @code{()}.
@end deffn

@deffn ScorekeeperProperty @code{messages} forms@dots{}
This property is a list of messages to send when
their conditions are satisfied.
Defaults to @code{()}.
@end deffn

@deffn ScorekeeperProperty @code{initial} value
This property is the value of the score upon game startup.
If this value is @code{-9999},
the scorekeeper does not maintain a numeric score.
Defaults to @code{-9999}.
@end deffn

@node Scorekeeper Bodies, Scorekeeper Functions, Scorekeeper Properties, Scorekeeper Forms

@subsection Scorekeeper Bodies

The forms in the body (the @code{do} property) of the scorekeeper
may be any of the forms listed here.

@deffn ScorekeeperForm @code{last-side-wins}
If supplied as the only symbol in the body, then the scorekeeper
implements the usual ``last side left in the game wins'' behavior.
@end deffn

@deffn ScorekeeperForm @code{if} test action
If the @i{test} evaluates to @code{true} or any nonzero number,
then the @i{action} will be done.
@end deffn

@deffn ScorekeeperForm @code{cond} (test actions@dots{}) @dots{}
This is like Lisp's cond.
@end deffn

@deffn ScorekeeperForm @code{stop} [ message ]
This stops the game immediately, with a draw for all sides.
@end deffn

@deffn ScorekeeperForm @code{win} [ sides ] [ own-message ] [ other-message ]
@end deffn

@deffn ScorekeeperForm @code{lose} [ sides ] [ own-message ] [ other-message ]
@end deffn

@deffn ScorekeeperForm @code{end} [ message ]
This scorekeeper action ends the game immediately.
@end deffn

@deffn ScorekeeperForm @code{add} exp [ side ]
This adds the result of evaluating @var{exp} to the score of the given side.
The value may be a negative number.
@end deffn

@node Scorekeeper Functions, Scorefile, Scorekeeper Bodies, Scorekeeper Forms

@subsection Scorekeeper Functions

@deffn ScorekeeperFunction @code{and} exps
@end deffn

@deffn ScorekeeperFunction @code{or} exps
@end deffn

@deffn ScorekeeperFunction @code{not} exp
@end deffn

@deffn ScorekeeperFunction @code{=} exp1 exp2
@end deffn

@deffn ScorekeeperFunction @code{/=} exp1 exp2
@end deffn

@deffn ScorekeeperFunction @code{>} exp1 exp2
@end deffn

@deffn ScorekeeperFunction @code{>=} exp1 exp2
@end deffn

@deffn ScorekeeperFunction @code{<} exp1 exp2
@end deffn

@deffn ScorekeeperFunction @code{<=} exp1 exp2
@end deffn

@deffn ScorekeeperFunction @code{sum} types properties [ test ]
@end deffn

@node Scorefile,  , Scorekeeper Functions, Scorekeeper Forms

@subsection Scorefile

@deffn GlobalVariable @code{scorefile-name} str
This variable supplies the name of the file to be used for recording
scores of people playing the game.
The default value is @code{""}, which disables the recording of scores.
@end deffn

@node History Forms, Battle Forms, Scorekeeper Forms, Reference Manual

@section History Forms

All the important events in a game are logged into a history.

@deffn Form @code{evt} date type sides data
This form creates a single historical event.
The @var{date} is the turn of the event's occurrence, while
the @var{sides} is a bit mask of sides that know about the
event, or @code{all} if all sides know about it.
@end deffn

@deffn GlobalConstant @code{all}
@end deffn

@deffn Form @code{exu} id type x y side props
This form defines an ``ex-unit'', which is a record of a unit that
existed previously.  It is similar to a unit, but has only a few
properties; type, id, position, side, name, and number.
Property names and semantics are nearly identical to their
counterparts for units.
@end deffn

@deffn EventType @code{log-started}
This event records when the recording of events began.
Multiple instances of this may occur, for instance if
logging were to be turned off and then on again.
@end deffn

@deffn EventType @code{log-ended}
@end deffn

@deffn EventType @code{game-started}
This event records the actual start of the game.
There should only be one in a game's history.
@end deffn

@deffn EventType @code{game-saved}
This event records that the game was saved.
@end deffn

@deffn EventType @code{game-restarted}
This event records that the game was restored and restarted from
a saved game.
@end deffn

@deffn EventType @code{game-ended}
@end deffn

@deffn EventType @code{side-joined} side
This event records when a side joined the game.
@end deffn

@deffn EventType @code{side-lost} side scorekeeper
This event records when a side lost.
@end deffn

@deffn EventType @code{side-won} side scorekeeper
This event records when a side won.
@end deffn

@deffn EventType @code{side-withdrew} side
This event records when a side withdrew from the game.
@end deffn

@deffn EventType @code{unit-created} side unit
This event records the creation of a unit.
@end deffn

@deffn EventType @code{unit-completed} side unit
This event records the completion of a unit.
@end deffn

@deffn EventType @code{unit-acquired}
This event records the acquisition of a unit,
for instance as a gift from another side.
@end deffn

@deffn EventType @code{unit-captured}
This event records the capture of a unit,
as an outcome of combat or from a direct attempt to capture.
@end deffn

@deffn EventType @code{unit-moved} unit x1 y1 x2 y2
This event records the movement of a unit.
@end deffn

@deffn EventType @code{unit-name-changed} unit1 unit2
This event records that a unit's name was changed.
@var{unit1} will be an ex-unit representing the unit
under its previous name.
@end deffn

@deffn EventType @code{unit-type-changed} unit1 unit2
This event records that a unit's type was changed.
@var{unit1} will be an ex-unit representing the unit
with its previous type.
@end deffn

@deffn EventType @code{unit-assaulted} unit1 unit2 x y
@end deffn

@deffn EventType @code{unit-damaged} unit hp1 hp2
@end deffn

@deffn EventType @code{unit-killed} unit
@end deffn

@deffn EventType @code{unit-died-in-accident} unit
@end deffn

@deffn EventType @code{unit-died-from-temperature} unit
@end deffn

@deffn EventType @code{unit-vanished} unit
@end deffn

@deffn EventType @code{unit-wrecked} unit
@end deffn

@deffn EventType @code{unit-wrecked-in-accident} unit
@end deffn

@deffn EventType @code{unit-revolted} unit
@end deffn

@deffn EventType @code{unit-surrendered} unit
@end deffn

@deffn EventType @code{unit-garrisoned} unit
@end deffn

@deffn EventType @code{unit-disbanded} unit
@end deffn

@deffn EventType @code{unit-starved} unit
@end deffn

@deffn EventType @code{unit-left-world} unit
@end deffn

The following event types are the results of actions.

@deffn EventType @code{action-ok}
@end deffn

@deffn EventType @code{action-error}
@end deffn

@deffn EventType @code{cannot-do}
@end deffn

@deffn EventType @code{insufficient-acp}
@end deffn

@deffn EventType @code{insufficient-material}
@end deffn

@deffn EventType @code{too-far}
@end deffn

@deffn EventType @code{too-near}
@end deffn

@deffn EventType @code{action-done}
@end deffn

@deffn EventType @code{insufficient-mp}
@end deffn

@deffn EventType @code{cannot-leave-world}
@end deffn

@deffn EventType @code{destination-full}
@end deffn

@deffn EventType @code{overrun-succeeded}
@end deffn

@deffn EventType @code{overrun-failed}
@end deffn

@deffn EventType @code{capture-succeeded}
@end deffn

@deffn EventType @code{capture-failed}
@end deffn

@deffn EventType @code{fire-into-outside-world}
@end deffn

@node Battle Forms, Types in General, History Forms, Reference Manual

@section Battle Forms

Battles always have exactly two ``sides'', referred to as
the attacker-list or A-list and the defender-list or D-list, so
as not to confuse them with sides in the game.

@deffn Form @code{battle} a-list d-list@dots{}
@end deffn

Each list has the form
@example
((<unit> <commitment>) ...)
@end example

@node Types in General, Unit Types, Battle Forms, Reference Manual

@section Types in General

Types are the foundation of @i{Xconq} game designs.
Nearly all the rules and game parameters are associated
with the unit, material, and terrain types.
There is no sort of type hierarchy; instead, most forms allow sets of types
to be used in the place of single types.

Each type has an index associated with it, starting from 0.
This index never appears directly, and cannot be set.
This does mean that types have an order, so the order in which
types are defined is sometimes significant.
These cases will be noted.
The order is always the order in which the types appear in the file.

@menu
* Type Names::
* Type Images::
* Documentation::
* Availability::
* Type Extension::
@end menu

@node Type Names, Type Images, Types in General, Types in General

@subsection Type Names

The names of types need not be distinct from each other,
but you run the risk of player confusion if they share names.

@deffn TypeProperty @code{name} string
This property is the specific name of the type.
This name will be displayed to players; the exact format
is up to the interface, but will typically
depend on the name's length and the space available in the display.
If no type names have been defined, the internal type name (see below)
will be used.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{long-name} string
This property is a fully spelled-out name for the type.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{short-name} string
This property is an abbreviated name of r
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{generic-name} string
This property is like @code{name}, but identifies the type less specifically,
and several types may have the same generic name.
If no generic names are defined, then the regular type names will be used.
This is useful when making abbreviated lists, so that related types
get counted together.
Defaults to @code{()}.
@end deffn

As an example of the distinction between type names and generic type name,
the names of a automobile type might be @code{"1965 Mustang"},
@code{"Mustang"}, and @code{"M"},
while the generic name is @code{"auto"}.
Then the interface could choose to display a parking lot as containing
either @code{"4 auto"} or @code{"2 Mustang 1 Edsel 1 Jeep"}.

Note that names specified as properties are strings only, and are
not defined as evaluable symbols.

@node Type Images, Documentation, Type Names, Types in General

@subsection Type Images

The interpretation of these properties is entirely up to each interface;
see the appropriate interface documentation for details.

@deffn TypeProperty @code{image-name} str
This property is the name of the type's image.
If undefined or unusable for some reason,
the interface will display the type in some default manner, such as
a solid-color square or a string.
@end deffn

For example, in X11,
the name might be the name of a file in the usual bitmap format, as
produced by the @var{bitmap} program.  The actual file name is produced
by appending @code{".b"}.
(The situation in X is actually more complicated than this.)
See the interface documentation for details on how the interface
uses the image.

@deffn TypeProperty @code{color} str
This property is the name of the preferred color for this type.
Both normal color names and the strings @code{"bg"} and @code{"fg"}
(meaning ``foreground color'' and ``background color'')
may be used.
If the image is in color, then this property has no effect.
Defaults to @code{"fg"}.
@end deffn

@deffn TypeProperty @code{char} str
This property supplies a single character for this type
(all characters after the first one in @var{str} are ignored).
Defaults to @code{""}.
@end deffn

@node Documentation, Availability, Type Images, Types in General

@subsection Documentation

@deffn TypeProperty @code{description-format} list@dots{}
This property defines the different ways in which
an instance or instances of this type may be described textually.
This information may be used in narrative descriptions and by some
interfaces.
If @code{()}, then the instance will be described in some default
fashion, such as (for units) @code{"the <side> <ordinal> <type>"}.
Defaults to @code{()}.
@end deffn

@deffn TypeProperty @code{help} string
This property is a brief (preferably one-line) description of the type.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{notes} strings@dots{}
This property is detailed documentation about the type.
The formatting of the strings is up to the interface,
but in general each string is a separate line,
the string @code{""} indicates a line break,
and two @code{""} in a row indicates a paragraph break.
Defaults to @code{()}.
@end deffn

@node Availability, Type Extension, Documentation, Types in General

@subsection Availability

It may be that a set of types is larger than strictly necessary for
a particular game.  You can make any type unavailable, which means
that irrespective of any other controls, that type cannot come into
play during a game.  You can also make it available only for particular
turns.

@deffn TypeProperty @code{available} n
If the value of this property is greater than 0, then this type is available
in the game on or after turn @var{n}.
If the value is less than 0, then the type is available,
but only until turn @var{-n}.
If the value is 0, then the type is never available.
Defaults to @code{1}, which means that the type is always available.
@end deffn

If a type becomes unavailable and there are units of that type in play,
then they will vanish immediately.

@node Type Extension, , Availability, Types in General

@subsection Type Extension

It may occasionally be necessary to add new kinds of
information to a type.
For instance, new synthesis methods may require special data,
or an interface may be able to use extra hints to improve its display.
The @code{extensions} property can be used to store this kind of data.

@deffn TypeProperty @code{extensions} properties@dots{}
This property is a catch-all for nonstandard type properties.
Anything may appear here, but it will only be interpreted as much as needed,
and unrecognized extensions will not be warned about (so if you misspell
one, you won't find out).
@end deffn

@node Unit Types, Terrain Types, Types in General, Reference Manual

@section Unit Types

@deffn Form @code{unit-type} symbol properties@dots{}
This form defines a new type of unit.
The @var{symbol} is required and must be previously undefined.
The bindings in @var{properties} are then added to the type one by one.
If no other name properties are defined, the @var{symbol} may be displayed
to players (see above).
You can define no more than 126 types of units.
@end deffn

The @var{symbol} here becomes the unit type's ``internal type name''
which is guaranteed unique.
To make synonyms for the internal type name, use @code{define}.

@deffn GlobalVariable @code{u*}
This variable evaluates to a list of all unit types,
listed in the order that they were defined.
This list always reflects the list of types at the moment it is evaluated.
@end deffn

@deffn GlobalVariable @code{non-unit}
This variable evaluates to a value that is NOT a unit type.
This is needed in several places to enable/disable features.
Use of this in any other way is an error,
and may or may not be detected before it causes a crash.
(Although described as a variable, its value cannot be changed.)
@end deffn

@menu
* Unit Naming::
* Class-Restricted Unit Types::
* Self-Unit Capable Units::
* Limits on Unit Quantities::
* Hit Points::
* Experience::
* Tech Levels vs Units::
* Opinions::
* Point Value::
@end menu

@node Unit Naming, Class-Restricted Unit Types, Unit Types, Unit Types

@subsection Unit Naming

@deffn UnitTypeProperty @code{namer} namer-id
This property is the namer that will be used to generate names for units,
if the unit's side does not have a namer, or the unit is
independent and not in any country.
Defaults to @code{0}, which leaves the unit unnamed.
@end deffn

@deffn UnitTypeProperty @code{assign-number} t/f
This property is true if the unit should have a serial number assigned to it
by the side it belongs to.
Serial numbers are maintained for each type on each side separately,
start at 1 for the first unit of the type, and increase by one each time.
Defaults to @code{true}.
@end deffn

@node Class-Restricted Unit Types, Self-Unit Capable Units, Unit Naming, Unit Types
@subsection Class-Restricted Unit Types

Sometimes the designer will want to make different sides have different types
of units.  Although this can be done by setting up scenarios appropriately,
that won't close all the loopholes that might allow a side to get units that
should only ever belong to another side.

The first step is to define a class for each side.  For instance,
a side named @code{"Rome"} might have a class @code{"Roman"},
while the sides named @code{"Aedui"} and @code{"Parisii"}
could both be in the class @code{"barbarian"}.

@deffn UnitTypeProperty @code{possible-sides} exp
This property restricts the unit type to only be usable
by a side meeting the conditions of @var{exp}.
If @var{exp} is a string, it restricts the unit type to only
be usable by a side whose class includes a matching string.
This may also be a boolean expression.
Independent units belong to a side whose class is @code{"independent"}.
The default of @code{""} allows the unit to belong to any side.
@end deffn

@node Self-Unit Capable Units, Limits on Unit Quantities, Class-Restricted Unit Types, Unit Types

@subsection Self-Unit Capable Units

The self-unit can be any type, including one that cannot act;
for instance, a capital city could be the self-unit, thus making
its defense all-important for a player.

@deffn GlobalVariable @code{self-required} t/f
This variable is true if each side is required to have a self-unit
at all times.
However, if no unit of a suitable type is available when the game begins,
then none will be required.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{can-be-self} t/f
This property says that the type of unit can represent the side directly.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{self-changeable} t/f
This property is true if the player can choose to change a self-unit of
this type at any time.
Otherwise the self-unit can be changed only if the current one dies.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{self-resurrects} t/f
This property is true if when the self-unit dies, another unit of an allowable type
becomes the self-unit automatically.
Defaults to @code{false}.
@end deffn

Observe that these parameters can be used to develop various forms of
backup, so that a player can start out as a capital city, resurrect as
a town, change self to one of several towns, then lose when all the towns
are lost.

@deffn UnitTypeProperty @code{direct-control} t/f
This property is true if a unit of this type can be controlled by its side
automatically.
If false, then it must be within range of a unit that can control it,
and is itself under control by the side.
Defaults to @code{true}.
@end deffn

@deffn Table @code{control-chance-at} u1 u2 -> n%
@end deffn

@deffn Table @code{control-chance-adjacent} u1 u2 -> n%
@end deffn

@deffn Table @code{control-chance} u1 u2 -> n%
@end deffn

@deffn Table @code{control-range} u1 u2 -> dist
This table gives the maximum distance from self-unit @var{u1}
at which units of type @var{u2} can be controlled directly.
Units further away always act on their own.
If this value is < 0, then @var{u1} can never directly control
any other @var{u2} on the side.
Defaults to @code{infinity}.
@end deffn

@node Limits on Unit Quantities, Hit Points, Self-Unit Capable Units, Unit Types

@subsection Limits on Unit Quantities

The effect of these is
to prevent any extra units from being created or from going over to a
side, regardless of the reason.
This happens by either preventing player actions that would
result in exceeding a limit (such as when building units), or by making
the unit vanish instantly (such as when capturing a unit).

@deffn GlobalVariable @code{units-in-game-max} n
This variable is the maximum number of all types of units, on all sides,
including independents, that may exist at any time, including initially.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@deffn GlobalVariable @code{units-per-side-max} n
This variable is the maximum number of units (of all types together)
that any side may have, at any time.  Events that would cause
the limit to be exceeded, such as capturing a unit, result in
either the unit vanishing or becoming independent.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

There is no limit on the number of units that may be independent.

@deffn UnitTypeProperty @code{type-in-game-max} n
This property is the maximum total of the given type, for all sides together.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@deffn UnitTypeProperty @code{type-per-side-max} n
This property is the maximum number of units of the given type allowed to each side.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@node Hit Points, Experience, Limits on Unit Quantities, Unit Types

@subsection Hit Points

A unit's hit points determine how healthy it is.
If a unit's hp goes below 1, it is either @dfn{wrecked},
meaning that it changes to a new type
@code{wrecked-type} or else it @dfn{vanishes},
meaning that it is completely cleared from the world.

@deffn UnitTypeProperty @code{hp-max} n
This property is the maximum number of hit points for (each part of) a unit.
Completed units start with this many hit points.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{parts-max} n
This property declares that a unit is really
an aggregate of @var{n} smaller identical units.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{wrecked-type} unit-type
This property is the type of unit that a unit with 0 hp will become.
For instance, a destroyed ``fort'' might become a ``rubble pile'' unit.
If its value is @code{non-unit}, then the destroyed unit just vanishes.
The @code{wrecked-type} of a type must be a different type.
Defaults to @code{non-unit}.
@end deffn

The transformation to the wrecked type does not change position or name.
The transformed unit has full hp, supplies are conserved as much as possible,
tooling is preserved, and any unit plan is erased.
It has the same number of parts, or as many as possible if that is fewer.
It may be that the
wrecked type is on terrain that it cannot survive on; in that case, it
will be wrecked again, repeating until the unit either vanishes
or is in a viable position, or this process has been repeated
more times than the number of unit types (prevents infinite loops).
Any excess occupants will be removed and either placed in another nearby
unit or in the open, or will vanish if there is no other option.

@deffn UnitTypeProperty @code{hp-recovery} n
This property is the number of 1/100 hp recovered per turn.
Recovery happens automatically at the end of each turn.
The amount @i{n} / 100 is recovered automatically each turn,
while @i{n} mod 100 is the percent chance of recovering
an additional 1 hit point.
Defaults to @code{0}.
@end deffn

@node Experience, Tech Levels vs Units, Hit Points, Unit Types

@subsection Experience

@deffn UnitTypeProperty @code{cxp-max} cxp
This property is the maximum combat experience this type of unit can have.
Defaults to @code{0}.
@end deffn

@node Tech Levels vs Units, Opinions, Experience, Unit Types

@subsection Tech Levels vs Units

Before it can do anything with a type of unit,
the side must have the appropriate tech level for that type,
which is just a number ranging from 0 up to @code{tech-level-max}.
Each type has a distinct tech level.

Tech levels always increase
(since they represent abstract knowledge rather than physical plant).
Tech can be transferred freely to any other side
via the message @code{tech} [xref to messages].

For each unit type, the following parameters define the minimum tech levels at
which sides can do various things.

@deffn UnitTypeProperty @code{tech-to-see} tl
This property is the minimum tech level that a side must have before it can see
a unit of this type.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-to-own} tl
This property is the minimum tech level
that a side must have in order to have a unit of this type.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-from-ownership} tl
This property is the tech level that may be reached
by acquiring a unit of this type.
Since this is expressed as a minimum,
multiple acquisitions have no additional effect.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-to-use} tl
This property is the minimum tech level that a side must have in order to
give actions to this type of unit.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-to-build} tl
This property is the minimum tech level that a side
must have in order to build this type of unit.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-max} tl
This property is the absolute maximum tech level possible for this type.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tech-crossover} u1 u2 -> n%
This table is the minimum tech level for @var{u2} that is guaranteed by a particular
tech level for @var{u1}, expressed as a percentage of the @code{tech-max}
for the types.
For instance, if @code{tech-crossover} is 80, and the tech level for @var{u1}
is 10 out of a max of 20, and the max for @var{u2} is also 20,
then the side has a tech for @var{u2} at least 8.
Defaults to @code{0}.
@end deffn

It is possible to gain some tech level just by being in the same game
with a side that is more advanced.

@deffn UnitTypeProperty @code{tech-leakage} .01tl
This property is the amount of tech level gain per turn that can happen
to any side's tech level that is less than the max of all sides in the game.
This only happens if at least one unit on the side has nonzero coverage
of a unit on a more advanced side.
Defaults to @code{0}.
@end deffn

@node Opinions, Point Value, Tech Levels vs Units, Unit Types

@subsection Opinions

@deffn UnitTypeProperty @code{has-opinions} t/f
This property is true if the unit has opinions about sides,
both other sides and its own.
Defaults to @code{false}.
@end deffn

@node Point Value, , Opinions, Unit Types

@subsection Point Value

Point values provide an abstract way to characterize the overall importance
of a unit type.
Point values figure into some scorekeepers, and are used by AIs.

@deffn UnitTypeProperty @code{point-value} n
This property is the ``value'' of a unit.
Defaults to @code{1}.
@end deffn

@node Terrain Types, Material Types, Unit Types, Reference Manual

@section Terrain Types

Terrain types are associated with the cells, borders,
connections, and coatings in a world.

@deffn Form @code{terrain-type} name properties@dots{}
This form defines a new type of terrain, named by @var{name}.
Details are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{t*}
This variable evaluates to a list of all terrain types,
listed in the order that they were defined.
@end deffn

@deffn GlobalVariable @code{non-terrain}
This variable has a value that is guaranteed not to be a terrain type.
@end deffn

@menu
* Terrain Subtypes::
* Terrain Compatibility::
* Other Terrain Properties::
* People::
@end menu

@node Terrain Subtypes, Terrain Compatibility, Terrain Types, Terrain Types

@subsection Terrain Subtypes

Terrain can appear in four different roles: as the interior of
a cell, as a border between cells, as a connection between cells,
or as a coating overlaying the normal terrain.
The terrain subtype says which role a type can play.

@deffn TerrainTypeProperty @code{subtype} subtype
This property is the role that the terrain type can appear in.
Defaults to @code{cell}.
@end deffn

@deffn GlobalConstant @code{cell}
This constant indicates that terrain can fill a cell.
All units in the open and with an altitude of 0 are assumed
to be surrounded by the cell terrain.
@end deffn

@deffn GlobalConstant @code{border}
This constant indicates that the terrain can be a border.
@end deffn

@deffn GlobalConstant @code{connection}
This constant indicates that the terrain can be a connection.
@end deffn

@deffn GlobalConstant @code{coating}
This constant indicates that the terrain can be a coating.
A @dfn{coating} is a temporary terrain modification.
The classic example is snow,
which effectively changes some kinds of terrain,
but not completely and usually not permanently.
Cells can have varying heaviness of each type of coating.
@end deffn

@deffn Table @code{coating-depth-min} t1 t2 -> n
In order for a coating @var{t1} to ``stick'',
this table says much must be added all at once to terrain @var{t2}.
A coating depth that drops below this will disappear immediately.
Defaults to @code{0}.
@end deffn

@deffn Table @code{coating-depth-max} t1 t2 -> n
This table is the upper limit on coating depth.
Defaults to @code{0}.
@end deffn

Terrain types may have additional subtype attributes that
are used only during synthesis, to select appropriate subtypes
for special purposes.

@deffn TerrainTypeProperty @code{subtype-x} n
This property is extra subtype information, used in synthesis.
Defaults to @code{no-x}.
@end deffn

@deffn GlobalConstant @code{no-x}
@end deffn

@deffn GlobalConstant @code{river-x}
This constant indicates that synthesis methods should treat this
type as a river.
The terrain type may be either a border or a connection.
@end deffn

@deffn GlobalConstant @code{valley-x}
This constant indicates that synthesis methods should treat this type
as a valley.
@end deffn

@deffn GlobalConstant @code{road-x}
This constant indicates that synthesis methods should treat this type
as a road.
@end deffn

@deffn TerrainTypeProperty @code{liquid} t/f
This property is true if the terrain type represents a liquid,
which means that adjacent cells of liquid must have the same elevation.
Defaults to @code{false}.
@end deffn

@node Terrain Compatibility, Other Terrain Properties, Terrain Subtypes, Terrain Types

@subsection Terrain Compatibility

Terrain types are not always mutually compatible.
Incompatible types may not be juxtaposed, either at
game setup time or by unit action during a game.

@deffn Table @code{adjacent-terrain-effect} t1 t2 -> t3
This table specifies what will happen to a cell of type @var{t1}
adjacent to a cell of type @var{t2}.  If @var{t3} is @code{non-terrain},
nothing will happen, otherwise it will become a cell of type @var{t3}.

If @var{t1} is a border type adjacent to a cell of type @var{t2},
and if @var{t3} is @code{non-terrain}, nothing will happen.
Otherwise, the border of type @var{t1} will be removed,
and if @var{t3} is a border type, a border of that type will be added.
The effect on connection types is analogous.

Defaults to @code{non-terrain}.
@end deffn

@node Other Terrain Properties, , Terrain Compatibility, Terrain Types

@subsection Other Terrain Properties

@deffn TerrainTypeProperty @code{elevation-min} dist
@end deffn
@deffn TerrainTypeProperty @code{elevation-max} dist
These properties define the minimum and maximum possible values
for the elevation in a cell of given terrain type.
Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-min} n
@end deffn
@deffn TerrainTypeProperty @code{temperature-max} n
These properties define the minimum and maximum possible values
for the temperature in a cell of given terrain type.
Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{wind-force-min} n
@end deffn
@deffn TerrainTypeProperty @code{wind-force-max} n
These properties define limits on wind force.
Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{clouds-min} n
@end deffn
@deffn TerrainTypeProperty @code{clouds-max} n
These properties define limits on cloud density.
Both default to @code{0}.
@end deffn

@node Material Types, Static Relationships Between Types, Terrain Types, Reference Manual

@section Material Types

Materials are materials that are manipulated in mass quantities.
In general, material types just index vectors of values attached
to other objects, such as unit supplies.

No more than 126 types of material may be defined.

@deffn Form @code{material-type} symbol properties@dots{}
This form defines a new type of material, named by @var{symbol}.
Details are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{m*}
This variable evaluates to a list of all material types,
listed in the same order as they were defined.
@end deffn

@deffn GlobalVariable @code{non-material}
This variable has a value that is never a material type.
@end deffn

@menu
* People::
@end menu

@node People, , , Material Types

@subsection People

A material type can be designated as representing people.

@deffn MaterialTypeProperty @code{people} n
This property is the actual number of individuals
represented by 1 of a material.
If 0, then the material type does not have people associated with it at all.
Defaults to @code{0}.
@end deffn

Multiple types of materials can represent different types of people,
so for example there could be one type @code{nomad} with 10 people/material,
and another type @code{urbanite} with 10,000 people/material.

The basic cell capacities for materials also constrain people
materials. There can be an additional limit on the number of individuals.

@deffn TerrainTypeProperty @code{people-max} n
This property is the maximum number of individuals allowed
in a cell of this type of terrain.
This is checked at the end of each turn;
any excess will be moved into adjacent cells or disappear entirely.
Defaults to @code{-1}, which allows any number of people in a cell.
@end deffn

@node Static Relationships Between Types, Vision, Material Types, Reference Manual

@section Static Relationships Between Types

In general, static relationships are those that must always hold
during a turn.  @i{Xconq} will usually only test these when
necessary, but this is up to the implementation.
From the players' and designers' point of view, these relationships
can never be violated, even temporarily.

@menu
* Occupants and Transports::
* Units and Terrain::
* Units and Materials::
* Terrain and Materials::
@end menu

@node Occupants and Transports, Units and Terrain, , Static Relationships Between Types

@subsection Occupants and Transports

A unit inside another unit is an ``occupant'' in a ``transport'',
even if the ``transport'' can never move.
There are two kinds of capacity.  Generic capacity is shared by
all different types, while guaranteed capacity is for a particular
type only.

@deffn UnitTypeProperty @code{capacity} n
This property is the limit on the sum of sizes of units that may occupy this
type of unit, not counting the exclusive capacities.
Defaults to @code{0}.
@end deffn

@deffn Table @code{unit-size-as-occupant} u1 u2 -> n
This table is the ``size'' of a (full-sized) unit @var{u1} when it is in
a transport @var{u2}.
Defaults to @code{1}.
@end deffn

@deffn Table @code{unit-capacity-x} u1 u2 -> n
This table is the number of units of type @var{u2} that are guaranteed
a place in a unit of type @var{u1}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-max} u1 u2 -> n
This table is the upper limit on the number of occupants of this type
(not counting @code{unit-capacity-x}).
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{occupant-total-max} n
This property is the upper limit on occupants of all types together.
Defaults to @code{-1}, which allows unlimited occupancy.
@end deffn

A unit that is an occupant may not always have the same capabilities
as when it is out in the open.  Its vision, combat, construction, and
capacity may be affected.

@deffn Table @code{occupant-vision} u1 u2 -> t/f
Defaults to @code{true}.
@end deffn

@deffn Table @code{occupant-combat} u1 u2 -> n%
This table defines the effect on the combat abilities
of a unit of type @var{u1} when an occupant in a unit of type @var{u2}.
If @code{0}, then the occupant cannot attack or fire.
Defaults to @code{100}.
@end deffn

@deffn Table @code{occupant-can-construct} u1 u2 -> t/f
This table is @code{true} if @var{u1} can
create or complete units while an occupant of @var{u2}.
Defaults to @code{false}.
@end deffn

@deffn Table @code{occupant-can-have-occupants} u1 u2 -> t/f
This table is @code{true} if @var{u1} can have occupants of its own
while an occupant of @var{u2}.
Defaults to @code{false}.
@end deffn

@node Units and Terrain, Units and Materials, Occupants and Transports, Static Relationships Between Types

@subsection Units and Terrain

This section describes relationships between units and terrain.
Units can be set to disappear or be wrecked on particular types of
terrain.  If the terrain can be occupied safely, there may be a limit
on the numbers of units that can be in the same cell.

@deffn Table @code{vanishes-on} u t -> t/f
This table is @code{true} if a unit @var{u} will disappear instantly if it
somehow ends up on terrain of type @var{t}.
Defaults to @code{false}.
@end deffn

@deffn Table @code{wrecks-on} u t -> t/f
This table is @code{true} if a unit @var{u} will wreck instantly if it
somehow ends up on terrain of type @var{t}.
Defaults to @code{false}.
@end deffn

@deffn TerrainTypeProperty @code{capacity} n
This property is the limit on the sum of unit sizes that may share this cell.
Defaults to @code{1}.
@end deffn

@deffn Table @code{unit-size-in-terrain} u t -> n
This table is the ``size'' of a (full-sized) unit @var{u} when it is
in/on the terrain @var{t}.
Defaults to @code{1}.
@end deffn

@deffn Table @code{terrain-capacity-x} u t -> n
This table is the number of (full-sized) units of type @var{u}
that are guaranteed to have a place in the cell.
Defaults to @code{0}.
@end deffn

Note that the units' sides are irrelevant;
the sizes of units of all sides are added together.
Limits are calculated separately for the connection and open terrain
in a cell.

@deffn UnitTypeProperty @code{stack-order} n
This property is the relative position of this type of unit within a stack of
different units.
Larger values put units higher in the stack.
The exact values are unimportant, they are just used as sort keys.
The use of this value is to ensure that particular types are ``seen first''
when looking at a cell, so for instance if a truck and a city are stacked
on the same cell, everybody will see the city and not the truck.
The owner of these units can still see them.
If the stack-order of two units is the same,
then the higher-numbered type will be higher in the stack.
Defaults to @code{0}.
@end deffn

There is a possible bizarrity with stacking limits and units that can't
see each other when in the same hex, namely that a player could be prevented
from moving a unit into a cell that looks like it has enough room.

@node Units and Materials, Terrain and Materials, Units and Terrain, Static Relationships Between Types

@subsection Units and Materials

Units can carry materials.

@deffn Table @code{unit-storage-x} u m -> n
This table is the space reserved specifically for each
type of material.
Defaults to @code{0}.
@end deffn

Materials that represent people may surrender to a unit in their cell.

@deffn Table @code{people-surrender-chance} u t -> n%
This table is the base chance that people in terrain of type @var{t}
will change sides if a unit of type @var{u} is in their cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{people-surrender-effect} u m -> n
This is a multiplier that takes the people type into account.
Defaults to @code{100}.
@end deffn

@node Terrain and Materials,  , Units and Materials, Static Relationships Between Types

@subsection Terrain and Materials

@deffn Table @code{terrain-storage-x} t m -> n
This table is the maximum amount of a material @var{m}
that may be present in a cell with terrain @var{t}.
Defaults to @code{0}.
@end deffn

@node Vision, Game Initialization, Static Relationships Between Types, Reference Manual

The parameters in this section define how sides get information about the
world, units, and other sides.

@section Vision

@menu
* Basic Vision::
* Weather Vision::
* Line of Sight::
* Spying::
@end menu

@node Basic Vision, Weather Vision, Vision, Vision

@subsection Basic Vision

@deffn GlobalVariable @code{see-all} t/f
This variable is @code{true} if everything in the world, units, terrain, etc,
is always visible at all times, including initially.
It takes precedence over @i{all} other visibility and spying parameters.
Defaults to @code{false}.
@end deffn

@deffn GlobalVariable @code{see-terrain-always} t/f
If this variable is @code{true}, then any side that has seen the terrain of a cell
will be informed if that terrain ever changes.
Defaults to @code{true}.
@end deffn

@deffn UnitTypeProperty @code{see-always} t/f
This property is @code{true} when a unit is always visible
after it has been seen once,
so that side changes, movements, etc will be seen forever afterwards.
If the unit moves into terrain that has not been seen,
then that terrain also becomes seen as well.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{see-occupants} t/f
This property is @code{true} when a unit's occupants are also seen
whenever the unit itself is under observation.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{spot-action} t/f
If this property is @code{true},
then the unit's chance to be seen by other sides will be
tested each time the unit acts in any way.
This property is in addition to the check at the beginning of each turn.
Defaults to @code{true}.
@end deffn

The people in a cell effectively view (for their side)
all units in that cell.
Some units can hide from the people.

@deffn Table @code{people-see-chance} u m -> n%
This table is the chance that the people of the
given type @var{m} will see a unit of type @var{u}.
This will be evaluated for each people type individually,
once at the beginning of each turn, and once for each populated cell
that the unit enters during the turn.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{vision-range} dist
This property is the maximum range of vision coverage by the unit.
A value of @code{-1} disables all vision,
@code{0} means only units in the same cell may be seen,
and @code{1} means units in adjacent cells may be seen.
Defaults to @code{1}.
@end deffn

@deffn Table @code{see-chance-at} u1 u2 -> n%
This table is the chance that a unit @var{u1} will see
another sides's unit of type @var{u2} when both are
in the same cell.
Defaults to @code{100}.
@end deffn

@deffn Table @code{see-chance-adjacent} u1 u2 -> n%
This table is the chance that a unit @var{u1} will see
another sides's unit of type @var{u2} when the two
are in adjacent cells.
Defaults to @code{100}.
@end deffn

@deffn Table @code{see-chance} u1 u2 -> n%
This table is the base chance that a unit @var{u1}
will see a unit @var{u2} in cells at distance 2 or greater.
Defaults to @code{100}.
@end deffn

@deffn Table @code{visibility} u t -> n
This table is the effect of terrain @var{t}
on a unit @var{u}'s chances of being seen.
Values less than 100 are reduced visibility,
values greater than 100 increase the unit's
chances to be seen.
Defaults to @code{100}.
@end deffn

@deffn Table @code{vision-night-effect} u t -> n
This table is the multiplier for unit @var{u}'s vision at night
in each type of terrain @var{t}.
Effect is to multiply with both vision range and see-chance.
Defaults to @code{100}.
@end deffn

@node Weather Vision, Line of Sight, Basic Vision, Vision

@subsection Weather Vision

@deffn GlobalVariable @code{see-weather-always} t/f
If true, then weather changes (in cells that have been seen) will always be reported.
Defaults to @code{true}.
@end deffn

@node Line of Sight, Spying, Weather Vision, Vision

@subsection Line of Sight

@deffn UnitTypeProperty @code{vision-bend} n
This property is the amount by which a unit can see ``around corners''.
0 means that vision is strictly line-of-sight,
while 100 means that elevations never obstruct vision.
Defaults to @code{100}.
@end deffn

@deffn Table @code{eye-height} u t -> dist
This propety is the additional elevation above the unit's position that a unit
can see with, when in the given terrain.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{thickness} dist
This property is the thickness of the terrain, which is the difference between
the ``ground'' of the terrain and its top.
Defaults to @code{0}.
@end deffn

@node Spying, , Line of Sight, Vision

@subsection Spying

A unit type can also be specified to do spying automatically.
The outcome of spying is calculated once/unit/turn,
at the beginning of the turn (after move calculation but before
any players can do anything).
Spying can happen to any unit not on the spying unit's side.

@deffn UnitTypeProperty @code{spy-chance} .01n%
This property is the chance that the unit will be successful at spying.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{spy-range} dist
This property is the maximum distance at which the unit will find out
something by spying.
Defaults to @code{0}.
@end deffn

@deffn Table @code{spy-quality} u1 u2 -> n%
This table gives the chance that @var{u1}'s spying will return information
about a unit of type @var{u2} that is within the spying range.
Defaults to @code{100}.
@end deffn

@node Game Initialization, Synthesis Methods, Vision, Reference Manual

@section Game Initialization

Game initialization always starts by resetting all the game-defining data
structures to an empty state.  This means no types, no world, etc.
Then @i{Xconq} reads and interprets
all of the game modules that have been requested.
These modules may overwrite each other arbitrarily.
Then any command line or startup options
are processed (this may involve an interactive dialog),
and the random number generator is initialized.
and players are matched with sides
(any sides needed for players will be created and named at this time).
@i{Xconq} then executes a number of @i{synthesis methods}
to do various kinds of setup.

(Some interfaces might allow for confirmation of the setup before
launching into the game proper, but this cannot be assumed.)

Since the details of good game synthesis can be complicated,
synthesis methods are simply wired-in pieces of code.
Each method is self-contained; it assumes the game state to be valid,
it will determine its own applicability and
produce a valid result.  It will also acquire any data that it
needs, so does not require any special setup;  however, a method
may fail to run if it cannot find that data.
For instance, the usual fractal
terrain generator needs percentiles for each terrain type, and
will not function without them.  It may be that all the requested
synthesis methods fail; this is OK if @i{Xconq}'s data is present
and consistent, but otherwise @i{Xconq} will shut itself down, since
it has no remaining alternatives (think of this as a serious
programming error and fix the game design).

@node Synthesis Methods, Setup Postprocessing, Game Initialization, Reference Manual

@section Synthesis Methods

The synthesis method list specifies which methods will be run,
and in what order.
After they have all been run, @i{Xconq} runs a consistency and completeness
check.  For instance, there should be a world with terrain everywhere.
Failure at this point is fatal; @i{Xconq} will either exit
or return to a game setup dialog.

@menu
* Synthesis Method List::
* Fractal World::
* Maze World::
* Random World::
* Earthlike World::
* Making Rivers::
* Making Roads::
* Making Countries::
* Making Independent Units::
* Making Weather::
* Making Initial Supply::
* Naming Geographical Features::
* Naming Units::
* Making a Random Date::
@end menu

@node Synthesis Method List, Fractal World, Synthesis Methods, Synthesis Methods

@subsection Synthesis Method List

@deffn GlobalVariable @code{synthesis-methods} method-list
This variable is a list of synthesis methods.
If the list is empty, no synthesis methods will be run.
@end deffn

The list of synthesis methods is ordered, and many contain duplicates,
so that a method can be run multiple times during setup.
Note that most of the existing methods will simply return if they
detect that their work has already been done, so multiple runs will
have no effect.

The default synthesis method list is effectively
@example
(make-fractal-percentile-terrain
 make-countries
 make-independent-units
 make-roads
 make-rivers
 make-weather
 init-supplies
 name-geographical-features
)
@end example

The synthesis method list may also contain items of the form

@example
("program" forms...)
@end example

For each of these items, @i{Xconq} will attempt to find and run
an external program named @code{"program"},
giving it as input the result of evaluating the @code{forms},
and then reading the output of the program, which must be a valid
game module.
The program must be capable of interpreting two arguments;
the first is the name of the input file it is to read from,
and the second is the name of the output file it must write to.
If successful, it should return with a result code of 0;
otherwise, @i{Xconq} will issue a warning to players.

Any further details will depend on your system,
since each will use different conventions.
Note that this is NOT a portable construct; you cannot assume that
everybody will have built and installed the program you're using.

@node Fractal World, Maze World, Synthesis Method List, Synthesis Methods

@subsection Fractal World

The fractal world synthesizer can make a variety of natural-looking terrain.
It relies on a number of parameters to govern a single algorithm.

@deffn SynthesisMethod @code{make-fractal-percentile-terrain}
This method generates the terrain layer of a world.
It works by generating two distinct layers of random blobs,
known as the ``alt'' and ``wet'' layers,
then decides on a terrain type for each cell.
If elevations are defined,
then this method will use the ``alt'' layer to produce elevations.
@end deffn

@deffn GlobalVariable @code{alt-blob-density} n
@end deffn
@deffn GlobalVariable @code{wet-blob-density} n
These variables are the number of blobs to put down,
expressed as number per 10,000 cells.
Defaults to @code{500}.
@end deffn

@deffn GlobalVariable @code{alt-blob-size} n.f%
@end deffn
@deffn GlobalVariable @code{wet-blob-size} n.f%
These variables are the average number of cells in a blob,
expressed as number per 10,000 cells.
Defaults to @code{100}.
@end deffn

@deffn GlobalVariable @code{alt-blob-height} n
@end deffn
@deffn GlobalVariable @code{wet-blob-height} n
These variables are the amounts by which to increment or decrement within a blob.
Defaults to @code{1000}.
@end deffn

@deffn GlobalVariable @code{alt-smoothing} n
@end deffn
@deffn GlobalVariable @code{wet-smoothing} n
These variables specify the number of averaging steps
to perform after the blobs have been generated.
Defaults to @code{2}.
@end deffn

@deffn TerrainTypeProperty @code{alt-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{alt-percentile-max} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-max} n%
These properties are
the percentiles of elevations and moistures that result in the given
terrain type.
Percentile ranges may overlap, in which case the earlier-defined
terrain type will be used.
If a cell has a alt and wet that does not fall in any of the ranges,
then terrain type 0 will be used there and players will be warned.
Mins defaults to @code{0}, maxes to @code{100}.
@end deffn

After the terrain has been assigned types, the method will give
a single type to all the cells on the edge of the area.

@deffn GlobalVariable @code{edge-terrain}
This variable is the type of terrain to fill in on all the edges of a world.
The edges of a world have little or no effect on the game,
but the terrain type should be something distinctive, so that players
can recognize the edges easily.  (For instance, ice is usually a good choice
for edges, but probably not on a map of Antarctica!)
Defaults to terrain type 0 (the first defined type).
@end deffn

@node Maze World, Random World, Fractal World, Synthesis Methods

@subsection Maze World

A maze consists of a set of randomly placed ``rooms'' connected by random
passages.

@deffn SynthesisMethod @code{make-maze-terrain}
This method creates terrain that looks like a maze.
It starts by randomly assigning terrain according to its @code{occurrence},
similarly to @code{make-random-terrain} below, then carves
out rooms and passages, filling each of those with terrain
types according to their respective occurrences.
@end deffn

@deffn TerrainTypeProperty @code{maze-room-occurrence} n
This property is the weighted amount of this terrain type
in rooms in the maze.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{maze-passage-occurrence} n
This property is the weighted amount of this terrain type
in passageways in the maze.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{maze-room-density} n
This variable is the fraction of the maze that is room,
expressed as the number of cells per 10,000 cells in the area.
Defaults to @code{1000}.
@end deffn

@deffn GlobalVariable @code{maze-passage-density} n
This variable is the fraction of the area that is passageway,
expressed as the number of cells per 10,000 cells in the area.
Defaults to @code{3000}.
@end deffn

This method will apply edge terrain as a last step.

@node Random World, Earthlike World, Maze World, Synthesis Methods

@subsection Random World

The random world generator just assigns terrain and elevations randomly.

@deffn SynthesisMethod @code{make-random-terrain}
This method generates completely random terrain.
It uses a simple weighting to govern how much
of each terrain type appears, and makes random elevations as well.
@end deffn

@deffn TerrainTypeProperty @code{occurrence} n
This property is the percentage of the world that will be of this type,
if the terrain is cell terrain.
If the terrain is border or connection, it is the probability
(expressed as .01% increments) that any direction of any cell
will have that border or connection.
Defaults to @code{1}.
@end deffn

@node Earthlike World, Making Rivers, Random World, Synthesis Methods

@subsection Earthlike World

Earthlike generation uses algorithms that more closely approximate
realistic terrain.

@deffn SynthesisMethod @code{make-earthlike-terrain}
This method generates terrain that approximates what actually
appears on Earth.
@end deffn

@node Making Rivers, Making Roads, Earthlike World, Synthesis Methods

@subsection Making Rivers

Rivers are borders or connections consisting of ``watery terrain''
that run downhill to regions of water.

@deffn SynthesisMethod @code{make-rivers}
This method looks for a border or connection
terrain type with a @code{subtype-x} of @code{river-x}.
then uses the world's elevation data to run rivers downhill
(always choosing the lowest of possible adjacent locations)
until they reach cell terrain with a @code{subtype} > 0.
This method will not run if there are no appropriate terrain types,
nor if there is no elevation data.
@end deffn

@deffn TerrainTypeProperty @code{river-chance} n%
This property is the chance that a river will start in or around a cell of this
terrain type.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{river-sink-terrain} t
If the value of this variable is a terrain type, then a cell completely
surrounded by river will be changed to be this type.
Defaults to @code{non-terrain}.
@end deffn

Note that the algorithm computes rivers in a deterministic way,
so high values of @code{river-chance} do not result in tangled rivers.

@node Making Roads, Making Countries, Making Rivers, Synthesis Methods

@subsection Making Roads

The road generation method makes networks of connection terrain between
particular unit types, usually those resembling cities.

@deffn SynthesisMethod @code{make-roads}
This methods synthesizes roads for an area.
For any connection type of terrain, if no layer has been created for it
already, and the type has a @code{subtype-x} of 3,
put down roads between any pair of units whose
@code{road-chance} is nonzero.
The method will attempt to share road routes whenever possible,
and choose terrain according to @code{road-into-chance}.
In addition, the method may also generate spur roads connecting
units to existing roads, and run roads from one edge of the
area to another.
@end deffn

@deffn Table @code{road-chance} u1 u2 -> n%
This table is the chance that a road will be laid, running
from a unit of type @var{u1} to one of type @var{u2}.
Note that is not a symmetrical relationship;
since roads follow random paths, if the @code{road-chance}
causes a road to be laid from @var{u1} to @var{u2},
and another from @var{u2} to @var{u1}, it is quite possible
that the result will be two different roads connecting
the two units.
Defaults to @code{0}.
@end deffn

@deffn Table @code{road-into-chance} t1 t2 -> n%
This table is the chance that a road will be chosen to pass
from terrain of type @var{t1} into terrain of type @var{t2}.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{spur-chance} n%
This property is the percentage chance that the unit will get a spur
road running from the unit to the nearest existing road.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{spur-range} dist
This property is the radius of the area that will be searched for an
existing road.
Defaults to @code{1}, which results in spurs connecting only to
roads in adjacent cells.
@end deffn

@deffn UnitTypeProperty @code{road-to-edge-chance} n%
This property is the percentage chance that the unit will have
a road running from the unit to some edge of the area.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{edge-road-density} n
This variable is the density of roads that run from one area edge
to another, expressed as the number per 10,000 cells in the area.
(note, not counting just edge cells).
Defaults to @code{0}.
@end deffn

@node Making Countries, Making Independent Units, Making Roads, Synthesis Methods

@subsection Making Countries

The @code{make-countries} method sets up the starting units for
each side, placing them in a confined area, separated from the
starting units of other sides and taking terrain preferences
into account.  If requested, this method will also expand the
country outwards by a specified amount, possibly placing additional
units in the process.

@deffn SynthesisMethod @code{make-countries}
This method works by looking for a likely place for the country,
randomly places a basic set of starting units within that area,
then expands the country outwards.
The parameters give you control over the mix of terrain types
in the country, as well as the size and relative positions of the
different countries.
This method runs on any side with fewer units than it is supposed
to start with, as given by the parameters below.
It places groups of units at locations separated from each other
by specified distances.
@end deffn

@deffn GlobalVariable @code{country-radius-min} dist
This variable is the radius of the country's initial area.
Defaults to @code{-1}, which allows the algorithm to calculate a ``reasonable''
country size appropriate to the given number of units.
@end deffn

@deffn GlobalVariable @code{country-separation-min} dist
@end deffn
@deffn GlobalVariable @code{country-separation-max} dist
These variables are the minimum and maximum
distances of country centers from each other, in cells.
If small, countries will mostly overlap;
if very large, then attempts to use small worlds will fail;
if the max and min are too close to each other, placements can also fail.
For both of these, a value of @code{-1} disables their effect.
Both default to @code{-1}.
@end deffn

The max separation bound needs to be satisfied for a country
with respect to only @i{one} other country,
so for instance the final layout may involve a long
``string'' of countries where the first and last countries are very far apart
from each other.
The minimum bound must be satisfied for all pairs of countries.

@deffn TerrainTypeProperty @code{country-terrain-min} n
This property is the minimum amount of terrain
that must be within the country's initial radius.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{country-terrain-max} n
This property is the most terrain of the given type that may appear.
If @code{-1}, then any amount may be present.
Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{start-with} n
@end deffn
@deffn UnitTypeProperty @code{independent-near-start} n
These properties set the number of units of the given type in a player's country.
These units are randomly scattered within the initial radius,
and the @code{favored} table (see below) decides which terrains
will be used.  Units may be placed inside each other; in fact,
units with no favored terrain will be made into occupants if possible.

The independent units will be placed after the ones belonging to the side,
so on the average they will get the less desirable locations in the country.
Both independent and the side's units will be named using the side's namers.

Both default to @code{0}.
@end deffn

@deffn Table @code{favored-terrain} u t -> n%
This table sets
the probability of the unit type being on the given type of terrain at the
outset.  A value of @code{0} is an absolute prohibition against placing
the unit on that type of terrain, thus every game must specify at least
one non-zero value for some terrain type and some initial unit type.
Defaults to @code{100}.
@end deffn

Once the initial country area has been set up,
then you can allow the countries to expand outwards.
Expansion occurs at the same rate for all countries.
Countries may expand into and through each other.
Expansion occurs as a number of @var{steps}, each step increasing
the radius of countries by 1 all around.

@deffn TerrainTypeProperty @code{country-growth-chance} n%
This property is the chance that a country will expand onto an unclaimed cell
of the given terrain type.
Defaults to @code{100}.
@end deffn

@deffn TerrainTypeProperty @code{country-takeover-chance} n%
This property is the chance that a country will expand onto another country's cell
of the given terrain type.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{unit-growth-chance} n.f%
This property is the chance that a unit of the given type will be placed
when the country expands onto a cell.
The unit will only be placed if the @code{favored} chance is also true.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{independent-growth-chance} n.f%
This property is the chance that an independent unit of the given type will be placed
when the country expands onto a cell.
The @code{favored} chance is also evaluated.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{unit-takeover-chance} n.f%
This property is the chance that a unit of the given type in another country and
belonging to another side will be given to the growing side.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{independent-takeover-chance} n.f%
This property is the chance that an independent unit of the given type in
another country will be given to the growing side.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{country-radius-max} dist
This variable is a cap on the country growth process.
Values between @code{0} and @code{country-radius-min}
prevent country growth entirely,
while a value of @code{-1} allows growth to encompass the entire world.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{country-units-max} n
This property is a cap on the number of units given to the side's country.
Defaults to @code{-1}, which disables any limit.
@end deffn

@deffn GlobalVariable @code{growth-stop-chance} n%
This variable is the chance that a country's growth will stop,
if during the current step no new cells were added
to the country.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{country-people-chance} n%
This property is the chance that the people's side will be changed to
match that for the country they are in.
Defaults to @code{100}.
@end deffn

@node Making Independent Units, Making Weather, Making Countries, Synthesis Methods

@subsection Making Independent Units

@deffn SynthesisMethod @code{make-independent-units}
This method scatters independent units randomly
over the world.
This method will not run if the specified density of independent units
has already
been achieved, for instance from a predefined world or from country placement.
Independent units that should be inside other independents will be
handled correctly.
@end deffn

@deffn Table @code{independent-density} u t -> n
This table is the total number of independent units appearing throughout the world,
at the rate of @var{n} per 10,000 cells
of the given terrain type.
Any independent units already placed are counted first,
so this value represents final density.
If the sum of values for a given unit type on all terrain types is nonzero,
then at least one unit of that type will
be placed, even if the world is very small (i.e. the calculation of
numbers rounds up not down).
Defaults to @code{0}.
@end deffn

This method uses the @code{favored-terrain} table as the chance that a given
unit will be placed at a randomly-chosen position,
and it will keep trying different positions until a suitable one is
found.

@deffn TerrainTypeProperty @code{independent-people-chance} .01n%
This property is the chance that the people of a cell with this terrain type
will be made independent.
Deafults to @code{0}.
@end deffn

@node Making Weather, Making Initial Supply, Making Independent Units, Synthesis Methods

@subsection Making Weather

Weather synthesis sets up an initial state for the weather.

@deffn SynthesisMethod @code{make-weather}
This method sets up weather-related layers,
including temperature, winds, and clouds.
@end deffn

@node Making Initial Supply, Naming Geographical Features, Making Weather, Synthesis Methods

@subsection Making Initial Supply

By default, all units start out empty of materials.
The supply initialization method gives each unit a starting supply,
according to the stockpile tables.

@deffn SynthesisMethod @code{make-initial-materials}
This method fills unit and cell supplies to specified levels.
It will fill all units in existence at the moment it runs,
including units that have not appeared yet.
Similarly, all cells will be filled.
@end deffn

@deffn Table @code{unit-initial-supply} u m -> n
This table is the amount of each material that each unit will start out with.
If the initial supply is greater than unit's capacity,
then the unit will just be filled to capacity.
Defaults to @code{0}.
@end deffn

@deffn Table @code{terrain-initial-supply} t m -> n
This table is the amount of material @var{m} that each cell
with terrain @var{t} will start out with.
This will be limited by the cell's capacity.
Defaults to @code{0}.
@end deffn

@node Naming Geographical Features, Naming Units, Making Initial Supply, Synthesis Methods

@subsection Naming Geographical Features

Although named geographical features don't affect the outcome of a game
in any way, they are useful for ``color'' and for identifying locations
more readably.

@deffn SynthesisMethod @code{name-geographical-features}
This method identifies and names regions as geographical features,
such as mountain ranges and islands.
@end deffn

@deffn GlobalVariable @code{feature-namers} feature-namer-list
This variable is a list of feature types and their associated namers.
This is used for features not intersecting any country
with a namer for the feature's type.
Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{feature-types} feature-expr-list
This variable is a list of feature types that may be identified.
Examples: @code{("lake" (group (sea shallows) 1))},
@code{("peak" (high-point 1 1))}

Defaults to @code{()}.
@end deffn

[need to document recognized feature types]

@node Naming Units, Making a Random Date, Naming Geographical Features, Synthesis Methods

@subsection Naming Units

@deffn SynthesisMethod @code{name-units-randomly}
This method gives names to previously-unnamed units,
using their usual namers.
@end deffn

@node Making a Random Date,  , Naming Units, Synthesis Methods

@subsection Making a Random Date

For extra color, games can be set up to start at a random date
within a given range.  If day or year effects are defined,
this also has the effect of making the game start at a random
time of day or year.

@deffn SynthesisMethod @code{make-random-date}
This method generates a random starting date, within specified
bounds.
@end deffn

@deffn GlobalVariable @code{initial-date-min} date
This variable is the earliest possible date for the game.
Defaults to @code{""}.
@end deffn

@deffn GlobalVariable @code{initial-date-max} date
This variable is the latest possible date for the game.
Defaults to @code{""}.
@end deffn

@node Setup Postprocessing, Naming and Text Generation, Synthesis Methods, Reference Manual

@section Setup Postprocessing

Some initialization steps will be done after all synthesis methods
have been run.  @i{Xconq} will always do these.

@menu
* Initial View::
@end menu

@node Initial View, , Setup Postprocessing, Setup Postprocessing

@subsection Initial View

By default, each side starts out knowing only what its units can
normally see at the beginning of the first turn.
These parameters add to that initial view.

@deffn GlobalVariable @code{terrain-seen} t/f
This variable is @code{true} if all the terrain of the world is known initially.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{initial-seen-radius} dist
This property specifies the radius of the area seen around each of
the starting units.
It computes visibility of terrain (cells and borders) only.
Defaults to @code{1} (which is a no-op if the unit's @code{vision-range}
is greater than or equal to 1).
@end deffn

@deffn UnitTypeProperty @code{already-seen} n%
This property is the chance to see units of this type at
the beginning of the game.
This applies only to units belonging to another side,
and on known terrain.
The effect is one-time, so if an @code{already-seen} unit changes
sides later on, other players will not see the change unless
they have the unit under observation for themselves.
Note that @code{see-always} implies @code{already-seen}.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{already-seen-independent} n%
This property is like @code{already-seen},
but applies to independent units specifically.
Defaults to @code{0}.
@end deffn

@node Naming and Text Generation, Actions, Setup Postprocessing, Reference Manual

@section Naming and Text Generation

@i{Xconq} can generate names for sides, units, and geographical features.
Although most naming happens during game setup, names may be assigned
throughout the course of a game, both automatically and by player request.

@menu
* Naming Sides::
* Namers::
* Naming Methods::
@end menu

@node Naming Sides, Namers, Naming and Text Generation, Naming and Text Generation

@subsection Naming Sides

Side naming is special, because several different but related names
have to be produced.

@deffn Variable @code{side-library} side-info@dots{}
This variable is a weighted list of groups of side properties,
each of which may be used to fill in a side.
@end deffn

The form of each side name entry is basically a subset of the
side's properties:
@example
([ weight ] ... (name <name>) ... (color <colors>) ...)
@end example
Each entry can include as many or as few of the attributes as desired;
any missing will be filled in from the usual defaults.
The optional @var{weight} is a number that adjusts the probability of selection
of the given side name set; it defaults to 1, and the probability is scaled
according to the sum of the weights for all the sides listed.
If any property value is a namer, then the namer will be run.
(Note that if multiple namers are specified, they cannot be guaranteed
to coordinate with each other, so you can end up with a side noun
that is inappropriate for its corresponding side name.)

@node Namers, Naming Methods, Naming Sides, Naming and Text Generation

@subsection Namers

Since one of the purposes of naming is to identify objects uniquely,
any name generator should be able to maintain some memory as to
what has been generated already.
The objects that do this are @dfn{namers}.

@deffn Form @code{namer} [ symbol/id ] method rejects@dots{}
This form defines an instance of a namer, with either the symbolic
name or numeric id.  If either matches the name or id of an existing
namer, then the old namer will be overwritten, otherwise a new one
will be created.
The @var{method} must be one of the naming methods listed below,
and @var{rejects} defines what names may not be produced (its exact
interpretation depends on the method).
@end deffn

@node Naming Methods,  , Namers, Naming and Text Generation

@subsection Naming Methods

As with general synthesis, @i{Xconq} has a number of @dfn{naming methods}
available.

An implementation is free to define additional naming methods.

@deffn NamingMethod @code{random} names @dots{}
This method picks a name from the given list of names
and removes that name from the list.
@end deffn

@deffn NamingMethod @code{junky}
This method produces a gobbledy-gook name, very techy-looking.
@end deffn

@deffn NamingMethod @code{grammar} root max-length rules@dots{}
This method defines a grammar, where @var{root} is the root symbol,
@var{max-length} is a limit on the length of the generated names
(in characters),
and @var{rules} is a list of rules of the form
@example
(@var{symbol} ([sym] [weight] @var{symbol/string/list} [n] @dots{}))
@end example
@end deffn

The generation process works by substituting one of the rule's alternatives
for the symbol, starting with the root symbol.
The probability of an alternative being selected is arrived at by
adding up the optional weights @var{weight} (assuming missing weights
to be @code{1}), and choosing with a probability of the weight
divided by the total sum of weights.
Thus the weights need not add up to any particular value.

Strings get used directly.
If a symbol in the rule's chosen expansion does not appear as the
lefthand side in any rule, then it will be handled as a string,
otherwise it will be expanded in turn.
If the symbol matches a namer's name, then that namer will be
run (passing the same object??) and its result incorporated.
A list should be a list of strings and symbols, and the expansion
of each will be concatenated.

@deffn GlobalConstant @code{any}
@end deffn

@deffn GlobalConstant @code{or}
@end deffn

@deffn GlobalConstant @code{reject}
A special rule headed by @code{reject} is a list of substrings
that should not appear in a generated name; this is a convenient
way to filter out particularly unlovely results.
@end deffn

@deffn GlobalConstant @code{capitalize}
Directs capitalization of a nonterminal.
@end deffn

[text is not actually different from a namer?]

@deffn Form @code{text} [ symbol/id ] method rejects@dots{}
@end deffn

@deffn GlobalVariable @code{action-messages} patterns
@end deffn

@deffn GlobalVariable @code{event-messages} patterns
@end deffn

@node Actions, Backdrop Environment Parameters, Naming and Text Generation, Reference Manual

@section Actions

The parameters in this section define and regulate the various actions that are
available to units during a game.

Actions always start and complete (including all of their effects)
within the same turn, and a unit can only do one at a time.

All actions are potentially available to all units, but the parameters
can be set so as to deny any action type to any unit type.
See the descriptions with each action type.

All action is limited by action points.
Each unit gets a certain number at the beginning of each
turn and expends them in the course of doing things.
The usual expenditure is
one point per action, but may be more, as defined for each type of action.
A unit action must always consume at least one action point.
Units can accumulate acp from turn to turn, and they can also reduce
acp below zero.

@menu
* Actions in General::
* Action Ordering::
* Movement Action::
* Entry Action::
* Research Action::
* Toolup Action::
* Unit Creation Actions::
* Unit Completion Action::
* Repair Action::
* Material Production Action::
* Material Transfer Action::
* Side Change Action::
* Disband Action::
* Part Transfer Action::
* Type Change Action::
* Combat Actions::
* Capture Action::
* Detonation Action::
* Terrain Alteration Actions::
@end menu

@node Actions in General, Action Ordering, Actions, Actions

@subsection Actions in General

@deffn UnitTypeProperty @code{acp-per-turn} acp
This property is the basic allowance of action points that a unit gets each turn.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-min} acp
This property specifies how far into ``action debt'' a unit can go
during a turn before it is prevented entirely from acting.
A unit with acp < 1 at the beginning of a turn cannot do anything at all.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-max} acp
This property is
the maximum number of action points that a unit can save up.
The value @code{-1} means that @code{acp-max} is equal to @code{acp}.
Extra acp is silently lost.
Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{free-acp} acp
This property is
the value is the amount by which the action points for some
action can exceed the unit's currently available acp
and still allow that action.
Defaults to @code{-1}, which means enough free acp to
allow any action.
@end deffn

Note that a unit with an acp of 0 is completely unintelligent, about like
a cow patty.  Cow patties can be useful for blocking paths, hiding behind,
and suchlike, and have the advantage that once they're in place, you don't
have to manage them.  Other units will have to pick them up and put them
down, of course.

@deffn Table @code{material-to-act} u m -> n
This table is a minimum amount of @var{m} needed for @var{u} to be able to act.
The material is not consumed.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-damage-effect} interpolation-list
This property is the effect of a unit's hp on its acp.
The input value is hp, while the output value is the acp to be added
instead of @code{acp-per-turn}.
This list does not extrapolate.
Defaults to @code{()}.
@end deffn

@deffn Table @code{acp-night-effect} u t -> n
This table is the multiplier for unit's acp at night in each type of terrain.
Defaults to @code{100}.
@end deffn

@deffn Table @code{acp-occupant-effect} u1 u2 -> n
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{acp-per-turn-min} acp
This property sets a lower limit on the effect of occupants,
damage, and other modifiers on the acp to be added at the beginning
of the turn.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-per-turn-max} acp
This property set the upper limit on the effect of occupants
and other modifiers to the acp added at the beginning of the turn.
Defaults to @code{-1}, which indicate no limit.
@end deffn

@node Action Ordering, Movement Action, Actions in General, Actions

@subsection Action Ordering

@deffn GlobalVariable @code{use-side-priority} t/f
This variable is @code{true} if the sides may only act one at a time;
otherwise, all sides and units may move simultaneously during a turn.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{action-priority} n
This property is the order in which units of this type will act.
Higher numbers act earlier.
If the difference between the priority of one type and another
is greater than 100, then the earlier-acting units must finish acting
before the later-acting units, otherwise a player can rearrange the actual
acting order as desired.
Defaults to @code{0}.
@end deffn

@node Movement Action, Entry Action, Action Ordering, Actions

@subsection Movement Action

Movement is the most common sort of action.
This section covers movement over open terrain;
the next section discusses interaction with transports.

The general theory of movement is that a unit not in a transport
crosses its current cell terrain to the edge of the cell,
crosses any border terrain, and then moves into the destination cell,
OR it moves onto connection terrain,
travels along connection terrain to the new cell, and maybe
moves off the connection.
If the unit starts in a transport, then the transport may ferry
the unit over some of the intervening terrain,
possibly as far as the unit's destination.

A unit's basic movement rate is defined by its @dfn{speed},
which is a ratio of the the unit's acp.
A speed of 100% means that the unit can potentially
enter as many cells as it has acp,
while a speed of 20% means that the unit uses at least
5 acp to enter a cell.

Movement can only succeed if several conditions are met:
the unit must be able to cross
the border terrain, the destination must be inside the world (but see below),
it must be able to exist on the terrain of the destination.

@deffn ActionType @code{move} x y z
This is the action that a unit performs to go from its current
location to the cell at @var{x,y} at altitude @var{z}.
The destination must be within the @code{move-range} of the unit.
@end deffn

@deffn UnitTypeProperty @code{acp-to-move} acp
This property is the number of acp a unit uses to do one move action.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{speed} n
This property is the basic multiplier relating acp to the number
of cells that may be entered during a turn.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{speed-damage-effect} interpolation-list
This property is the unit's speed if it is damaged.
The input value is the unit's hp, while the result value is the
unit speed to use instead of @code{speed}.
Defaults to @code{()}.
@end deffn

@deffn Table @code{speed-occupant-effect} u1 u2 -> n%
This table is the percent change in the speed
of type @var{u1} for each occupant of type @var{u2}.
If the basic speed of @var{u1} is @code{0},
then the multiplication is performed
as if the speed were @code{1} instead.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{speed-wind-effect} list
This property is a list that describes the effect of wind
on the unit's speed.  The effect is calculated using the
wind in the cell that the unit is entering (not its current
location?).  The form of the list is
@example
((<angle-list> <value>) ...),
<value> = <number> | ((<force> <number>) (<force> <number>) ...)
@end example
where @i{angle-list} is a single number, list of number, or the
symbol @code{all}.  For hex areas, the angles are 0 for downwind
(same direction), 1, 2, and 3 for directly upwind (opposite direction).
The @i{force} is the wind force in the cell, and @i{number} is the
multiplier for the speed, with @code{100} having no effect, numbers
less than @code{100} decreasing the unit's speed, and numbers greater
than @code{100} increasing it.
Defaults to @code{()}.
@end deffn

@deffn UnitTypeProperty @code{speed-min} mp
This property is the worst-case speed of a unit.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{speed-max} mp
This property is the upper bound on a unit's movement in one turn. (?)
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{move-range} n
This property is the maximum distance allowed to the destination cell.
Defaults to @code{1}.
@end deffn

The product of a unit's acp and its speed is its available @dfn{movement points}.
Any move between cells will cost at least one movement point.
Some mp costs may be negative, but the total mp for a move will always
be at least 1.

@deffn Table @code{mp-to-leave-terrain} u t -> mp
This table is the mp cost to leave a cell of type @var{t}.
If @var{t} is a border type, this cost is never used.
If @var{t} is a connection type, this cost is the cost of leaving the
connection terrain for the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of leaving the cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{mp-to-enter-terrain} u t -> mp
This table is the mp cost to enter a cell of type @var{t}.
If @var{t} is a border type, this cost is the
cost of crossing the border.
If @var{t} is a connection type, this cost is the cost of entering the
connection terrain from the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of entering the cell.
Defaults to @code{1}.
@end deffn

@deffn Table @code{mp-to-traverse} u t -> mp
This table gives the cost to travel
along a connection or border of the given type.
(note that the other costs are irrelevant if
unit starts and ends its movement on the connection).

A special type of move known as a @dfn{border slide} can occur when the
endpoints of a border touch on the start and destination cells.
Sliding works like normal movement
that happens to end up on a nonadjacent cell.
Same rules for permissibility apply.
If the value is negative, then border sliding is not possible.

Defaults to @code{1}.
@end deffn

If both enter/traverse/leave and enter/leave movement is possible,
then @i{Xconq} will automatically choose the cheapest alternative.

Each unit type has a range of altitudes within which it normally operates.

@deffn Table @code{altitude-min} u t -> n
This table is the minimum altitude possible for each type of unit
on each type of terrain.
Defaults to @code{0}.
@end deffn

@deffn Table @code{altitude-max} u t -> n
This table is the maximum altitude possible for each type of unit
on each type of terrain.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{mp-to-leave-world} mp
This property is an additional move cost to leave the world entirely.
To leave, the unit must be within its @code{move-range} of an edge,
and have sufficient mp to move into the terrain in the edge cell
designated as the destination of the move.
If the value is @code{-1}, then the unit may never leave.
Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{free-mp} mp
This property is the amount by which the move points can ``go into the red''
and still allow one more move.
Defaults to @code{0}.
@end deffn

ZOC is exerted only over units out in the open, has no effect on occupants,
unless they leave their transport.
Occupants can themselves exert a ZOC,
if @code{occupant-can-fight} is true.
ZOC applies to all units on a hostile side.

@deffn Table @code{zoc-range} u1 u2 -> dist
This table is the maximum distance at which type @var{u1}
exerts a ZOC over type @var{u2}.
A value of @code{0} means that the unit controls only its own cell,
and a value of @code{-1} means that the unit does not exert a ZOC at all.
Defaults to @code{0}.
@end deffn

@deffn Table @code{zoc-into-terrain} u t -> t/f
This table is @code{true} if the unit exerts its ZOC into terrain @var{t}.
Defaults to @code{true}.
@end deffn

@deffn Table @code{zoc-from-terrain-effect} u t -> n
Defaults to @code{100}.
@end deffn

@deffn Table @code{mp-to-enter-zoc} u1 u2 -> mp
This table specifies extra movement points needed to enter the ZOC.
@code{-1} prevents entry entirely.
Defaults to @code{-1}.
@end deffn

@deffn Table @code{mp-to-leave-zoc} u1 u2 -> mp
This table specifies extra movement points needed to leave the ZOC.
@code{-1} prevents departure entirely.
Defaults to @code{0}.
@end deffn

@deffn Table @code{mp-to-traverse-zoc} u1 u2 -> mp
This table specifies extra movement points needed to move within the ZOC.
@code{-1} prevents traversing entirely.
Defaults to @code{0}.
@end deffn

If multiple units exert a ZOC into the same cell, then the mp cost
is the maximum of the different ZOC costs.

Units may use up some of their materials when they move.
Consumption happens after the move action, and only for successful moves.

@deffn Table @code{material-to-move} u m -> n
This table is the amount of each material that a unit of type @var{u}
must have in order to be able to move.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-per-move} u m -> n
This table is the amount of each material used by a unit to do one move action.
The amount taken is independent of terrain.
If the unit has less than the required amount of any of these materials,
it is immobilized until it gets more (this is tested before each move
action; note that this does not affect any other action, including
entering and leaving transports).
Defaults to @code{0}.
@end deffn

@node Entry Action, Research Action, Movement Action, Actions

@subsection Entry Action

Units can be inside other units, and have units inside them, in a
tree-like fashion.  There is no limit on the depth of the tree,
but most occupant-transport relationships have other limits.

@deffn ActionType @code{enter} unit
This is the action to enter the given @var{unit}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-enter-unit} acp
This property is the number of acp a unit uses to do one entry action.
Defaults to @code{1}.
@end deffn

@deffn Table @code{can-enter-independent} u1 u2 -> t/f
This table is true if a unit @var{u1} can enter an independent unit @var{u2}.
Defaults to @code{false}.
@end deffn

Entering and leaving incur mp costs as does movment,
but units with a speed of 0 may enter and leave transports.

@deffn Table @code{mp-to-enter-unit} u1 u2 -> n
This table is the extra movement points required for @var{u1}
to enter the transport @var{u2},
and vice versa (i.e. how much of transport's time is consumed by the process).
Defaults to @code{0}.
@end deffn

@deffn Table @code{mp-to-leave-unit} u1 u2 -> n
Similar to entry cost.
Defaults to @code{0}.
@end deffn

Note that these mp consumptions need not be symmetrical
between occupant and transport,
so for instance a passenger can use 2 of its mp to get on a transport,
while costing the transport only one of its mp.

@deffn Table @code{ferry-on-entry} u1 u2 -> ferry-type
@end deffn
@deffn Table @code{ferry-on-departure} u1 u2 -> ferry-type
This table specifies how much intervening terrain the unit @var{u2}
entering or leaving transport @var{u1}
will have to cross on its own (and thus incur the terrain's mp costs and
limitations).
Defaults to @code{over-border}.
@end deffn

@deffn GlobalConstant @code{over-nothing}
This constant indicates no ferrying,
occupant must pay all costs to go to destination cell.
@end deffn

@deffn GlobalConstant @code{over-own}
This constant indicates that the transport ferries over terrain
of its own cell.
@end deffn

@deffn GlobalConstant @code{over-border}
This constant indicates that the transport ferries over any
border terrain also.
@end deffn

@deffn GlobalConstant @code{over-all}
This constant indicates that the transport ferries to destination cell,
effectively putting occupant on middle of cell,
on connection terrain if necessary.
@end deffn

@node Research Action, Toolup Action, Entry Action, Actions

@subsection Research Action

Research is an action performed by a unit with the sole effect
of increasing its side's tech level.
Research cannot be performed by independent units.

@deffn ActionType @code{research} u
This is the action of researching the unit type @var{u}.
If the action is valid, then the tech level of the side
will increase.
Unit types with any tech crossover will also have their tech
levels adjusted.
@end deffn

@deffn UnitTypeProperty @code{acp-to-research} acp
This property is the number of action points used up by one research action.
Defaults to @code{0}, which disallows research.
@end deffn

@deffn Table @code{tech-per-research} u1 u2 -> .01n
This table is the gain in tech level resulting from a research action, expressed as
1/100 of a level.  This value is stochastic.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-per-turn-max} tl
This property is a ceiling on the total gain of tech level possible in one turn
for each side and this unit type.
Defaults to @code{9999}.
@end deffn

@node Toolup Action, Unit Creation Actions, Research Action, Actions

@subsection Toolup Action

There are several stages in the construction of a unit: tooling up,
creation, and completion.  Tooling up is where the building unit
prepares to build, creation is the step where the new unit comes into
existence, and completion is where the new unit is brought up to being
operational.

For the player, this is mostly automatic; if tooling must be
done first, a user command to build will generate the appropriate actions.

Once the technology has been achieved, a unit that intends to construct
other units may need to tool up.
This is expressed as @dfn{tool points} or @dfn{tp}.
Tool points start at zero, can be increased by tooling actions,
and may gradually decline (representing wear and tear on the equipment).

@deffn ActionType @code{toolup} u
This is the action of tooling up to build a unit of type @code{u}.
The result is an increase in the tp for the acting unit.
@end deffn

@deffn UnitTypeProperty @code{acp-to-toolup} acp
This property gives the number of acp needed to do a toolup action.
Defaults to @code{0}, which disallows tooling up.
@end deffn

@deffn Table @code{tp-per-toolup} u1 u2 -> tp
This table is the number of tp gained by one tooling action.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-to-build} u1 u2 -> tp
This table is the number of toolup points needed before a unit of type @var{u1}
can create or build a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-max} u1 u2 -> tp
This table is the maximum possible tooling.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-attrition} u1 u2 -> tp
This table is the number of .01 tool points automatically lost at
the end of each turn.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-crossover} u1 u2 -> n%
This table is the number of tool points for @var{u2} that is
guaranteed to exist, expressed as a percentage of the tool
points for @var{u1}.
For instance, if @code{tp-crossover} is 80,
and a unit's tool points for @var{u1}
is 10 out of a max of 20, and the max for @var{u2} is also 20,
then the unit will have tool points for @var{u2} at least 8.
Defaults to @code{0}.
@end deffn

@node Unit Creation Actions, Unit Completion Action, Toolup Action, Actions

@subsection Unit Creation Actions

When a constructing unit is tooled up, the build action creates a unit
immediately and puts it in its designated location, whether inside the
unit doing the building or somewhere nearby.  This new unit, however, is
incomplete, representing the keel of the ship or the surveyor's
lines for an airstrip.  Incomplete units are thus basically skeletons,
with some unit characteristics, but unable to move or act in any way.
They also cannot have any occupants, unless the occupants are of a type
that can complete the unit.  Those occupants do not derive any protection
or other advantages from occupying the incomplete unit, and they are not
affected by the @code{occupant-can-build} limitation.

@deffn ActionType @code{create-in} u unit
This action creates a new unit of type @var{u} occupying the given
unit @var{unit}.
The unit @var{unit} must have room for the new unit.
@end deffn

@deffn ActionType @code{create-at} u x y z
This action creates a new unit of type @var{u} in the open at
@var{x,y,z}.
The cell must have room for this new unit.
@end deffn

@deffn Table @code{acp-to-create} u1 u2 -> acp
This table is the acp used by a unit of type @var{u1}
to create a a unit of type @var{u2}.
If zero, then @var{u1} cannot create a @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{create-range} u1 u2 -> dist
This table is the maximum distance at which a unit of type @var{u1}
can create a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cp-on-creation} u1 u2 -> cp
This table is the completeness of a unit of type @var{u2} when
created by a unit of type @var{u1}.
Defaults to @code{1}.
@end deffn

@deffn Table @code{material-to-create} u m -> n
This table is the total amount of a material type @var{m}
needed to create a unit of type @var{u}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-on-creation} u m -> n
This table is the amount of a material type @var{m}
consumed to create a unit of type @var{u}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{supply-on-creation} u m -> n
This table is the amount of supply of each material type @var{m}
to give a newly created unit of type @var{u}.
This supply is newly generated, does not come from anywhere else.
(Note that players could cheat by creating units, taking their supply,
and never completing them.)
Defaults to @code{0}.
@end deffn

@node Unit Completion Action, Repair Action, Unit Creation Actions, Actions

@subsection Unit Completion Action

Once an incomplete unit has been created,
other units can help to complete it.

@deffn ActionType @code{build} unit
This action adds to the completeness of @var{unit}.
If the unit becomes complete, it will be given its initial supply,
acp, name, etc.
@end deffn

@deffn Table @code{acp-to-build} u1 u2 -> acp
This table is the acp used up by one build action by a unit of type @var{u1}
when buiding a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cp-per-build} u1 u2 -> cp
This table is the amount of completeness of a unit of type @var{u2}
added by each completion action performed by a unit of type @var{u1}.
If @code{0}, then @var{u1} cannot contribute to completing @var{u2}.
Defaults to @code{1}.
@end deffn

@deffn Table @code{material-to-build} u1 m -> n
This table is the amount of each material type @var{m}
that @var{u1} must have in order to build anything at all.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-per-build} u2 m -> n
This table is the total amount of each material type @var{m}
consumed by the completion of a unit of type @var{u2}.
To calculate the consumption of a single build action,
this amount is divided by @var{u2}'s cp and multiplied by the
number of cp added by the action.  Fractions round up when
the unit's cp is low, so that the full consumption happens.
Defaults to @code{0}.
@end deffn

@deffn Table @code{build-range} u1 u2 -> dist
This table is the maximum distance allowed between a unit of type @var{u1}
and the incomplete unit of type @var{u2} it is working on.
Defaults to @code{0}, which requires the two units to be in
the same cell.
@end deffn

At a given point, incomplete units can make progress towards
completion on their own.  This is automatic because incomplete
units are unable to act, and occurs at a constant specified rate.
Automatic completion always occurs, even if other units are doing
build actions at the same time.  The incomplete unit must have
any necessary supplies.

@deffn UnitTypeProperty @code{cp-to-self-build} cp
This property is the minimum completeness of the unit necessary before it
can work on itself.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{cp-per-self-build} cp
This property is the completeness added each turn when a unit works on itself.
Defaults to @code{0}.
@end deffn

@deffn Table @code{supply-on-completion} u m -> n
This table is the minimum amount of supply of each material type @var{m}
guaranteed to a newly completed unit of type @var{u}.
If not already available to the unit, it will be newly generated.
Defaults to @code{0}.
@end deffn

@node Repair Action, Material Production Action, Unit Completion Action, Actions

@subsection Repair Action

Units can restore their own and each other's hp by doing repairs.
Repair requires a repair action.
The action points for this action
are taken from both the unit being repaired and
the repairer (using the same table @code{acp-to-repair}).
When a unit repairs itself, the action cost is counted once only.

@deffn ActionType @code{repair} unit
This is the action of repairing the given @var{unit}.
@end deffn

@deffn Table @code{acp-to-repair} u1 u2 -> acp
This table is the number of action points used up
by a unit of type @var{u1}
doing one repair action on a unit of type @var{u2}.
Defaults to @code{0}, which disallows the action.
@end deffn

@deffn Table @code{hp-per-repair} u1 u2 -> .01hp
This table is the hundredths of a hp that a single repair action
by a unit of type @var{u1} restores to a unit of type @var{u2}.
The fraction of this over 100 is added to hp directly,
while the < 100 fraction is added probabilistically.
(For example, a value of 160 means that 1 hp will be added for
each action, and there is a 60% chance that a second hp will
be added also.)
Defaults to @code{0}.
@end deffn

Materials may be needed and/or consumed during repair.
The materials will be taken from the
unit being repaired, then from the repairer.

@deffn Table @code{material-to-repair} u m -> .01n
This table is the amount of each material type @var{m} needed
for one repair action.
As with @code{hp-per-repair},
the < 100 part is average, and > 100 is guaranteed.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-per-repair} u m -> .01n
This table is the amount of each material type @var{m}
used up by a repair action.
@end deffn

The repairing unit must also not be too damaged itself to do repairs.

@deffn Table @code{hp-to-repair} u1 u2 -> hp
This table is the minimum hp level required of a unit of type @var{u1}
to repair a unit of type @var{u2}.
If less, then @var{u1} is too damaged to do any repairing.
Defaults to @code{1}, which allows repair always.
@end deffn

The following are not really part of the repair action definition, since
they occur automatically, but they share many of the tables above.

@deffn Table @code{auto-repair} u1 u2 -> .01hp
This table is the amount of repair (in 1/100 hp) that @var{u1} will do
on any unit of type @var{u2} within range (@code{auto-repair-range}).
As with @code{hp-per-repair},
the < 1.00 part is average, and > 1.00 is guaranteed.
Material requirements and usage are as for repair actions.
Defaults to @code{0}, which disallows auto-repair.
@end deffn

@deffn Table @code{auto-repair-range} u1 u2 -> dist
This table is the distance out to which @var{u1} will auto-repair
any damaged @var{u2}.  A value of @code{0} requires the two units
to be in the same cell, while a value of @code{-1} means that
@var{u2} must be either an occupant or transport of @var{u1}.
Defaults to @code{0}.
@end deffn

@node Material Production Action, Material Transfer Action, Repair Action, Actions

@subsection Material Production Action

Units can produce materials by explicit action.

@deffn ActionType @code{produce} m
This action results in a quantity of material @var{m}
coming into existence.
@end deffn

@deffn Table @code{acp-to-produce} u m -> acp
This table is the acp used up by one @code{produce} action.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-per-production} u m -> n
This table is the amount of material produced by @var{u}
when acting to produce type @var{m}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-to-produce} u m -> .01n
@end deffn

@node Material Transfer Action, Side Change Action, Material Production Action, Actions

@subsection Material Transfer Action

Although most movement of materials between units happens automatically
(see backdrop economy description, section ???),
players can also do it explicitly.
Players can both take materials from other units, and give a unit's
materials to others.

@deffn ActionType @code{transfer} unit m n
This is the action of transferring supply to the given unit @var{unit}.
The desired amount is @var{n};  if @var{m} is a valid material type,
then only that type will be transferred, otherwise the action will
transfer all types of materials possible.
The actual transfer amounts may be less than @var{n}.
@end deffn

@deffn Table @code{acp-to-unload} u1 m -> acp
@end deffn
@deffn Table @code{acp-to-load} u1 m -> acp
These tables are the number of action points used up by one material transfer
action from @var{u1} to @var{u2}.
The amount is independent of the material type being transferred.
If either value is @code{0}, then the material cannot be transferred.
Defaults to @code{0}.
@end deffn

@deffn Table @code{unload-max} u1 m -> n
@end deffn
@deffn Table @code{load-max} u2 m -> n
These two tables determine how much of material @var{m} can be transferred out
of a unit of type @var{u1} and into one of type @var{u2}
in one transfer action.
The actual quantity transferred by the action
is the minimum of these two values.
A value of @code{0} disallows manual transfer.
Both default to @code{-1}, which allows any amount to be transferred.
@end deffn

@node Side Change Action, Disband Action, Material Transfer Action, Actions

@subsection Side Change Action

@deffn ActionType @code{change-side} side
This is the action of changing the unit's side to @var{side}.
The @var{side} can be any allowable side, and the unit
may be any unit controlled by the actor's side.
@end deffn

@deffn UnitTypeProperty @code{acp-to-change-side} acp
If the value of this property is greater than 0,
then this type of unit can be ordered to change to another given side.
If the unit is not a type that can act, then the side change happens
immediately, instead of as an action, and no acp cost is incurred.
The type must also be allowed to be on the new side.
Defaults to @code{0}.
@end deffn

@node Disband Action, Part Transfer Action, Side Change Action, Actions

@subsection Disband Action

Disbanding is the voluntary and controlled destruction of a unit,
performed by the unit itself or another unit.
A disbanded unit always vanishes, rather than changing to its
@code{wrecked-type}.

@deffn ActionType @code{disband} unit
This is the action of removing hp from @var{unit}.
The unit will vanish if all its hit points are gone.
@end deffn

@deffn UnitTypeProperty @code{acp-to-disband} acp
If the value of this property is greater than 0,
then this is the acp that will be used up to do one disband action.
If the unit is not a type that can act, then the disband happens
immediately, instead of as an action, and no acp cost is incurred.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{hp-per-disband} hp
This table is the number of hp lost in a disband action.
Defaults to @code{0}, which disallows disbanding.
@end deffn

A disbanded unit can be scavenged for materials.

@deffn Table @code{supply-per-disband} u m -> n%
This table is the percentage of the unit's supply that is recovered
from a single disband action.
If the value is zero, then the unit's supply will not be
recovered by the disbanding process, and be lost permanently.
If any supply remains when the unit's hp is 0, then that
supply will be lost also.
Defaults to @code{100}, which means that the entire supply
will be recovered on the first disband action.
@end deffn

Note that if an essential supply is 100% recovered before the unit
is completely disbanded, then it may die from starvation first.
A partly-disbanded unit may still acquire supply
from nearby units, via the backdrop economy.

@deffn Table @code{recycleable-material} u m -> n
This table is the quantity of each type of material that becomes available
when a unit is completely disbanded.
The materials go to transports, occupants, and nearby units, in that order.
Any materials exceeding capacities of these units will be discarded.
These materials become available only when the unit vanishes.
Defaults to @code{0}.
@end deffn

@node Part Transfer Action, Type Change Action, Disband Action, Actions

@subsection Part Transfer Action

Units of variable size can transfer parts of themselves to other
units, or create a new unit.

@deffn ActionType @code{transfer-part} n unit
This action moves @var{n} parts of the actee to @var{unit},
or creates a new unit if @var{unit} is omitted.
If @var{n} is negative, this takes from @var{unit} instead.
If the action takes all the parts of any involved unit,
then it vanishes.
@end deffn

@deffn UnitTypeProperty @code{acp-to-transfer-part} acp
This property is the number of acp used up by the unit
when doing a part transfer action.
If 0, then part transfer is not allowed.
Defaults to @code{0}.
@end deffn

@node Type Change Action, Combat Actions, Part Transfer Action, Actions

@subsection Type Change Action

Units may change their type.

@deffn ActionType @code{change-type} u
This action changes the type of the actee unit to the type @var{u}.
Upon changing, the relationships of the unit with the world and
with other units will be recalculated; occupants that can no longer
stay in the unit will be ejected or disappear.  The unit itself
may vanish or wreck, if it is in the open on a terrain type that will
cause units of the new type to vanish or wreck.
@end deffn

@deffn Table @code{acp-to-change-type} u1 u2 -> acp
This table is the number of acp needed to change a unit of
type @var{u1} into a unit of type @var{u2}.
If the value is 0, then the change is never possible.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-to-change-type} u m -> n
This is the amount of each material type @var{m} required for a unit
to change into a unit of type @var{u}.
Defaults to @code{0}.
@end deffn

@node Combat Actions, Capture Action, Type Change Action, Actions

@subsection Combat Actions

@i{Xconq} combat is somewhat abstract; the attacking player decides what sort
of attack to mount and perhaps when to retreat, but all else happens
automatically.

Combat may last longer than a single action;
it is then called a @dfn{battle} and divided into @dfn{rounds}.
The battle exists until one participant has a commitment of zero.
Units in a battle need not attack, and no damage will occur if none do so,
but they cannot move away until no longer committed.

The attacker/defender distinction applies only to a single action.

@deffn ActionType @code{attack} unit commit
This action is a direct attack on the given @var{unit},
at a commitment level of @var{commit}.
The @var{unit} must be known to the attacking unit's side.
@end deffn

@deffn ActionType @code{overrun} x y z commit
This action is a combined attack/capture/move action.
The basic theory of an overrun is that the actor will attack,
capture, or co-occupy the cell at @var{x,y}, elevation @code{z},
with a commitment of @var{commit}.
The exact effects depend on the types and sides of units in the destination.
@end deffn

@deffn Table @code{acp-to-attack} u1 u2 -> acp
This table is the number of action points used up by a unit @var{u1}
when attacking a unit of type @var{u2}.
If the value is 0, attack is not allowed.
Defaults to @code{1}.
@end deffn

@deffn Table @code{acp-to-defend} u1 u2 -> acp
This table is the number of action points used up by a unit @var{u1}
when defending against an attack by a unit of type @var{u2}.
If the value is 0, attack is not allowed.
Defaults to @code{1}.
@end deffn

@deffn Table @code{attack-range-min} u1 u2 -> dist
This table is the minimum distance at which a unit can attack another.
A value of 0 means that units in the same cell can fight.
Defaults to @code{0}.
@end deffn

@deffn Table @code{attack-range} u1 u2 -> dist
This table is the maximum distance at which a unit can attack another.
A value of 1 means that units in adjacent cells may fight, while a
value of 0 means that only units in the same cell may fight.
Defaults to @code{1}.
@end deffn

One round of combat consists of an attack, a reaction,
and a calculation of effects.

The defender's reaction is completely automatic, and occurs as part of the
combat round.  The defender's side does not get a chance to
decide what to do until the next round,
although doctrine may constrain the set of reactions.

@deffn Table @code{surrender-chance-per-attack} u1 u2 -> n%
This table is the chance that @var{u2} will surrender to @var{u1}
immediately upon being attacked.
Defaults to @code{0}.
@end deffn

@deffn Table @code{withdraw-chance-per-attack} u1 u2 -> n%
This table is the chance that @var{u2} will retreat from @var{u1}
immediately upon being attacked.
Defaults to @code{0}.
@end deffn

@deffn Table @code{acp-for-retreat} u1 u2 -> acp
This table is the extra acp that @var{u2} can get in order
to make a withdrawal possible.
Defaults to @code{0}.
@end deffn

@deffn Table @code{counterattack} u1 u2 -> n
This table is the strength of a defender's reaction to an attack.
If 0, the defender does not counterattack;
if 100, the defender counterattacks at the same level as
if it attacked normally.
Defaults to @code{100}.
@end deffn

In an overrun action,
if all the defending units are destroyed,
the attacker has sufficient acp and mp,
and the destination is safe to enter,
then the attacker can move into the defenders' cell.

Firing is a kind of attack that can take place at a distance,
involves no commitment or counterattack,
and for which the type of ammo may be selected.

@deffn ActionType @code{fire-at} unit m
This is the action of firing at a given @var{unit}.
If @var{m} is a valid material type, then that type will be used as ammo,
otherwise all available types will be used together.
@end deffn

@deffn ActionType @code{fire-into} x y z m
This is the action of firing into the cell at @var{x,y}.
If @var{z} is a valid altitude, then the fire will be concentrated
on units at that elevation.
If @var{m} is a valid material type, then that type will be used as ammo,
otherwise all available types will be used together.
@end deffn

@deffn UnitTypeProperty @code{acp-to-fire} acp
If this property is greater than 0, this type may attack by firing.
Defaults to @code{0}.
@end deffn

@deffn Table @code{acp-to-be-fired-on} u1 u2 -> acp
This table is the acp lost when a unit is being fired upon.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{range} dist
This property is the maximum distance to which a unit can fire.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{range-min} dist
This property is the minimum distance to which a unit can fire.
Defaults to @code{0}.
@end deffn

Both attack and fire combat calculate hits and damage in
a similar way, although they may use different tables.

@deffn Table @code{hit-chance} u1 u2 -> n%
This table is the basic chance that a unit of type @var{u1} will
actually hit a unit of type @var{u2}.
If the hit chance is @code{0}, then the unit may never attack
a unit of that type.
Defaults to @code{0}.
@end deffn

@deffn Table @code{fire-hit-chance} u1 u2 -> n%
This table is the basic chance that fire from a unit of type @var{u1} will
actually hit a unit of type @var{u2}.
If the hit chance is @code{0}, then the unit may never
fire at a unit of that type.
If the value is @code{-1}, then the value of this is the same
as the value of @code{hit-chance}.
Defaults to @code{-1}.
@end deffn

@deffn Table @code{attack-terrain-effect} u1 t -> n%
@end deffn
@deffn Table @code{defend-terrain-effect} u2 t -> n%
@end deffn
@deffn Table @code{fire-attack-terrain-effect} u1 t -> n%
@end deffn
@deffn Table @code{fire-defend-terrain-effect} u2 t -> n%
These tables specify the
effect of attacker's and defender's respective terrains on
@code{hit-chance} or @code{fire-hit-chance}.
These chances are multiplied with the basic hit chance.
Default to @code{100}.
@end deffn

@deffn Table @code{hit-cxp-effect} u1 u2 -> n
This table is the effect of combat experience on hit chance.
Its value is interpolated according to actual experience
(@var{n} is the effect when @var{u1} is at its maximum
possible experience), then multiplied with the hit chance.
Defaults to @code{100}.
@end deffn

The effectiveness of fire may be less at long ranges.  If the
range to the target is greater than @code{hit-falloff-range},
the chance of hitting it will be reduced by the interpolation
between the short-range chance and that chance multiplied by
the value of @code{hit-at-max-range-effect}.  For example, if
a unit's range is 4, its hit falloff range is 1,
the basic hit chance is 60%, and the max range effect is 50%,
then its hit chance at range 2 is 50%, at range 3 is 40%, and
at range 4 is 30%.

@deffn Table @code{hit-falloff-range} u1 u2 -> n
This table is the maximum range at which the effectiveness of combat
is @i{not} affected by distance.
Defaults to @code{1}.
@end deffn

@deffn Table @code{hit-at-max-range-effect} u1 u2 -> n%
This is the multiplier for the effectiveness of firing at the
maximum range possible.
Defaults to @code{100}.
@end deffn

@deffn Table @code{damage} u1 u2 -> hp
This table is the basic amount of damage caused by a successful attack.
The value is a dice spec.
Defaults to @code{1}.
@end deffn

@deffn Table @code{fire-damage} u1 u2 -> hp
This table is the basic amount of damage caused by a successful firing.
The value is a dice spec.
If the value is @code{-1}, then it is the same as @code{damage}.
Defaults to @code{-1}.
@end deffn

Damage done by combat is always prorated by commitment;
the table values are for attacks at full commitment.

@deffn Table @code{damage-cxp-effect} u1 u2 -> n
This table is the effect of combat experience on damage.
Its value is interpolated according to actual experience
(so that @var{n} is the effect when @var{u1} is at its maximum
experience), then multiplied with both the dice size and the
addend of the damage spec.
Defaults to @code{100}.
@end deffn

@deffn Table @code{hp-min} u1 u2 -> hp
This table is the lowest hp possible for @var{u1} from attacks by @var{u2}.
Further attacks by @var{u2} are still valid, but can do no further damage.
Defaults to @code{0}.
@end deffn

You can set a unit to use a material as ammo.

@deffn Table @code{consumption-per-attack} u1 m -> n
@end deffn
@deffn Table @code{hit-by} u2 m -> n
These tables specify material consumption in combat.
For each material @code{m}, the min of these two values is the amount
of u1's supply used up in an attack on u2.
Both default to @code{0}.
@end deffn

@deffn Table @code{material-to-fight} u m -> n
This table is a minimum of each material type @var{m} that a unit must
have to engage in any sort of combat.
This minimum is not necessarily used up in combat, it just needs to
be present.
Defaults to @code{0}.
@end deffn

Transports can protect their occupants, and vice versa.

@deffn Table @code{protection} u1 u2 -> n%
This table gives the effect of occupants of type @var{u1} on the chance
of another unit's attack hitting their transport @var{u2},
as well as the effect of the transport @var{u1} on the chance that
occupants of type @var{u2} will be hit.
This is a multiplier, where 100 has no protection, values less than
100 decrease hit chance, and values greater than 100 increase it.
Each occupant will be taken into account when computing transport's
protection.
Defaults to @code{100}.
@end deffn

A transport's destruction may leave occupants stranded on hex,
will do some sort of auto-escape or die if terrain is hostile.

Units stacked together can protect each other.

@deffn Table @code{stack-protection} u1 u2 -> n%
This table is the effect of units of type @var{u1} on attacks
on units of type @var{u2} that are in the same cell.
The effect is similar to that described for the @code{protection}
table.
Defaults to @code{100}.
@end deffn

Several other side-effects of combat may also be defined.

Units can retreat if they are about to be damaged; the retreat attempt
is automatic, and will be in a valid direction that is away from the attacker.
The retreat attempt will fail if there is no direction that the unit may
move, or if has insufficient materials, acp, etc to do the movement.
If the attempt is successful, then the unit will not be damaged;
otherwise it must take the hit.

@deffn Table @code{retreat-chance} u1 u2 -> n%
This table is the chance that @var{u2} will attempt to retreat
if it is hit by @var{u1}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cxp-per-combat} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
by surviving a combat round with @var{u2}.
Both attackers and defenders gain experience equally.
Defaults to @code{0}.
@end deffn

@node Capture Action, Detonation Action, Combat Actions, Actions

@subsection Capture Action

A unit may attempt to capture another unit directly.
If successful, the captured unit's side changes to that of the capturing unit.

@deffn ActionType @code{capture} unit
This is the action of capturing the given @var{unit}.
@end deffn

@deffn Table @code{acp-to-capture} u1 u2 -> acp
This table is the number of acp used up by a @code{capture} action.
Defaults to @code{0}, which disallows capture.
@end deffn

@deffn Table @code{bridge} u1 u2 -> t/f
This table is true if a unit of type @var{u1} can be captured by a unit of
type @var{u2} even if @var{u1} is on a type of terrain impassable to
the capturing unit.
Defaults to @code{false}.
@end deffn

@deffn Table @code{capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{independent-capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture an independent unit
of type @var{u2}.  If the value is @code{-1}, then the chance of capture
is given by the @code{capture-chance}.
Defaults to @code{-1}.
@end deffn

@deffn Table @code{scuttle-chance} u t -> n%
This table is the chance that a unit whose capture is guaranteed will destroy
itself instead.  Scuttling is destructive, so unit changes to @code{wrecked-type}.
Occupants of an about-to-be-captured unit will also attempt to scuttle.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-escape-chance} u1 u2 -> n%
This table is the chance that an occupant @var{u1} will escape during the capture
of a unit of type @var{u2}.
Occupants that do not escape are either captured themselves or destroyed,
depending on their type and the capturing unit's side.
Defaults to @code{0}.
@end deffn

@deffn Table @code{hp-to-garrison} u1 u2 -> n
This table is the number of hp that will be taken from the capturing
unit @var{u1} in order to guard a captured @var{u2}.
If the amount is the unit's full hp, then the unit will vanish
and any occupants will be distributed to the captured unit, to open
terrain, or will vanish themselves if there is no other option.
Defaults to @code{0}.
@end deffn

@deffn Table @code{countercapture} u1 u2 -> n
This table defines the defending unit's reaction to the capture
attempt.
If 0, then the unit does not react to the capture attempt.
Defaults to @code{0}.
@end deffn

Captures can also affect combat experience, but has different effects
on the capturing and captured units.

@deffn Table @code{cxp-per-capture} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
for capturing @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{cxp-on-capture-effect} n
This property gives the change in a unit's cxp due to being captured,
expressed as a multiplier.
Defaults to @code{100}.
@end deffn

@node Detonation Action, Terrain Alteration Actions, Capture Action, Actions

@subsection Detonation Action

Detonation is an action and/or behavior that causes damage indiscriminately.
The action specifies the location of the detonation,
which may be in the unit's cell or an adjacent one.
A unit that detonates loses hp, changing to its @code{wrecked-type}
if it loses all of its hp.
It also hits every unit within a specified radius.
Detonation may also affect terrain within a specified radius.

@deffn ActionType @code{detonate} x y z
This action detonates the actee at the given location @var{x,y,z}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-detonate} acp
This property is the number of action points used by one detonate action.
Defaults to @code{0}, which disallows detonation.
@end deffn

@deffn UnitTypeProperty @code{hp-per-detonation} hp
This property is the number of hp lost in each detonation.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-unit-range} u1 u2 -> dist
This table gives the range of effect from detonation of @var{u1}.
The severity falls off according to the inverse square law
extrapolated from the adjacent cell damage.
(1/4 severity at range 2, 1/9 at 3, etc.)
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-damage-at} u1 u2 -> hp
This table is the severity of @var{u1}'s hit on a unit @var{u2} in the same cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-damage-adjacent} u1 u2 -> hp
This table is the severity of @var{u1}'s hit on a unit @var{u2} in an adjacent cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-terrain-range} u t -> dist
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-terrain-damage-chance} u t -> n%
Defaults to @code{0}.
@end deffn

@deffn Table @code{terrain-damaged-type} t1 t2 -> n
Relative chance that terrain of type @var{t1} damaged by a detonation
will change into another type @var{t2}.
Defaults to @code{0}.
@end deffn

The following tables and properties can be used for units that cannot
detonate deliberately by doing a detonate action.

@deffn Table @code{detonate-on-hit} u1 u2 -> n%
This table is the chance that a hit on @var{u1}
by a unit of type @var{u2} will cause it to detonate (once).
Noncombat reductions in hp, such as attrition, have no effect.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{detonate-on-death} n%
This property is the chance that if this type is about to die from a combat hit,
it will detonate first.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonate-on-capture} u1 u2 -> n%
This table is the chance that a unit of type @var{u1} will detonate if a capture
by a unit of type @var{u2} is about to succeed.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonate-on-approach-range} u1 u2 -> dist
When a unit of type @var{u2} on a non-trusted [?] side
appears at a distance of @var{dist}
or less, then @var{u1} will detonate.
If @code{-1}, then unit will not detonate upon approach.
Defaults to @code{-1}.
@end deffn

@deffn Table @code{detonation-accident-chance} u t -> n.f%
This table is the chance that the unit will detonate spontaneously.
This is checked once/turn, at the beginning of the turn, and also
upon each entry to a cell, if moving.
Defaults to @code{0}.
@end deffn

@node Terrain Alteration Actions,  , Detonation Action, Actions

@subsection Terrain Alteration Actions

@deffn ActionType @code{alter-terrain} x y t
This action changes the type of the cell at @var{x,y} to @var{t}.
@end deffn

@deffn ActionType @code{add-terrain} x y dir t
This action adds a connection or border of type @var{t}
to the cell at @var{x,y}, in direction @var{dir}.
@end deffn

@deffn ActionType @code{remove-terrain} x y dir t
This action removes a connection or border of type @var{t}
to the cell at @var{x,y}, in direction @var{dir}.
@end deffn

@deffn Table @code{acp-to-add-terrain} u t -> n
@end deffn
@deffn Table @code{acp-to-remove-terrain} u t -> n
For auxiliary terrain types, these tables are the costs to add or remove.
For cell terrain, the costs of removing the old type and adding the
new type are added together.
If the value is 0, then that type of terrain may not be added
or removed.  As a special exception, cell terrain may have a cost to
remove of 0, so that the sum of add and remove costs can be as low as 1;
in that case, a value of -1 disallows removal.
Both default to @code{0}.
@end deffn

@deffn Table @code{alter-terrain-range} u t -> n
This table is the maximum distance at which a unit can alter terrain @var{t}.
Defaults to @code{0}, which means that the unit can change only the
terrain in its own cell.
@end deffn

Note that if @code{see-terrain-always} is false, then other sides will not
see the terrain change unless they are viewing the altered terrain.

@node Backdrop Environment Parameters, Backdrop Economy Parameters, Actions, Reference Manual

@section Backdrop Environment Parameters

This section describes how to set up backdrop computations affecting the environment.

@menu
* Years and Days::
* Temperature Variation::
* Temperature Effects::
* Wind Variation::
@end menu

@node Years and Days, Temperature Variation, Backdrop Environment Parameters, Backdrop Environment Parameters

@subsection Years and Days

Cyclic changes in the environment are governed by a yearly cycle
or a daily cycle whose length must be defined.

@deffn WorldProperty @code{year-length} n
This property is the number of turns in an annual cycle.
If less than @code{2}, then no seasonal effects will be calculated.
Defaults to @code{0}.
@end deffn

@deffn WorldProperty @code{day-length} n
This property is the number of turns in a single day.
If less than @code{2}, then day and night will not be calculated.
Defaults to @code{0}.
@end deffn

Note that @code{year-length} and @code{day-length} are
completely independent of each other, and it is possible
to have days that are longer than years.

@deffn AreaProperty @code{initial-year-part} n
This property is the season of the first turn in the game.
Defaults to @code{0}.
@end deffn

@deffn AreaProperty @code{initial-day-part} n
This property is the hour of the first turn in the game,
in 100ths of a day part.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{season-names} list
This global is a list of which turns in a year should be called
which seasons.  It has the form @code{(... (n1 n2 name) ...)}.
Defaults to @code{()}.
@end deffn

@deffn UnitTypeProperty @code{acp-season-effect} interpolation-list
This property is the effect of the seasons on acp.
The input value is the year part, and the result value
is added to the basic @code{acp-per-turn}.
Defaults to @code{()}.
@end deffn

@node Temperature Variation, Temperature Effects, Years and Days, Backdrop Environment Parameters

@subsection Temperature Variation

@deffn TerrainTypeProperty @code{temperature-average} n
This property is the average temperature for each type of terrain.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-variability} n
This property is the amount of totally random variation
in the temperature in each cell.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{temperature-year-cycle} ((x y) interpolation-list)@dots{}
This global is a list of interpolation lists used to set basic temperatures
at given points in the area.  The input value for each list is the current year
part, while the result is the temperature at @var{x},@var{y}.
Then for each point in the area, its temperature is the interpolation of the
temperature at the two nearest given points.
Defaults to @code{()}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-moderation-range} distance
This property is the radius of the area whose raw temperatures will be averaged
to get the actual temperature.
This can be very time-consuming to calculate,
so only values of 0 (no averaging)
and 1 (average with adjacent cells) are recommended.
Defaults to @code{0}.
@end deffn

@node Temperature Effects, Wind Variation, Temperature Variation, Backdrop Environment Parameters

@subsection Temperature Effects

@deffn UnitTypeProperty @code{acp-temperature-effect} interpolation-list
This property is the effect of temperature on acp.
The input value is temperature, and the result value
is multiplied with acp, after it has been modified for
night effect, but before modification for season.
The result is divided by 100, so an effect < 100 reduces acp, an effect
of 100 has no effect, and an effect > 100 increases acp.
Defaults to @code{()}.
@end deffn

@deffn UnitTypeProperty @code{consumption-temperature-effect} interpolation-list
This property is the effect of temperature on material consumption.
Defaults to @code{()}.
@end deffn

@deffn UnitTypeProperty @code{temperature-attrition} interpolation-list
This property is the effect of temperature on a unit's hp.
The input value is temperature, and the result value is the
number of hp that the unit will lose each turn at that temperature.
Defaults to @code{()}.
@end deffn

Transports can protect their occupants from temperature extremes.

@deffn Table @code{temperature-protection} u1 u2 -> t/f
@end deffn

@node Wind Variation, , Temperature Effects, Backdrop Environment Parameters

@subsection Wind Variation

@deffn TerrainTypeProperty @code{wind-force-average} n
This property is the average wind force in a type of terrain.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{wind-force-variability} n%
This property is the chance that the wind in a cell will increase
or decrease in force each turn.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{wind-variability} n%
This property is the chance that the wind in a cell will
change direction each turn.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{wind-mix-range} n
This variable is the radius out to which winds interact.
If 0, then winds in adjacent cells can vary independently
of each other, and do not interact in any way.
Defaults to @code{0}.
@end deffn

@node Backdrop Economy Parameters, Random Events, Backdrop Environment Parameters, Reference Manual

@section Backdrop Economy Parameters

The following parameters control the automatic production, distribution, and
consumption of materials by units and by cells.

@menu
* Unit Production and Consumption::
* Terrain Production and Consumption::
* Supply Lines::
@end menu

@node Unit Production and Consumption, Terrain Production and Consumption, , Backdrop Economy Parameters

@subsection Unit Production and Consumption

Units can be set to always produce some amount of material without
taking explicit action.

@deffn Table @code{base-production} u m -> n
This table is the basic amount of each material @var{m}
produced by a unit of type @var{u} in each turn.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-base-production} u m -> n
This table is the base production of each material @var{m}
when a unit of type @var{u} is an occupant.
Defaults to @code{0}.
@end deffn

@deffn Table @code{productivity} u t -> n%
This base is the percentage productivity of a unit
of type @var{u} when on terrain of type @var{t}.
This is multiplied with the basic production rate to get actual material
production, so productivity of @code{0} completely disables production on
that terrain type, and productivity of @code{100} yields the rate
specified by @code{base-production}.
Defaults to @code{100}.
@end deffn

@deffn Table @code{productivity-min} u m -> n
@end deffn
@deffn Table @code{productivity-max} u m -> n
These tables are the
lower and upper bounds on actual production after multiplying by
productivity.
Default to @code{0} and @code{9999}, respectively.
@end deffn

@deffn Table @code{base-consumption} u m -> n
This table
sets the amount of materials consumed by the unit in a turn, even if it
doesn't move or do anything else.
Defaults to @code{0}.
@end deffn

@deffn Table @code{hp-per-starve} u m -> hp
If the unit runs out of a material that it must consume,
this table specifies how many hp it will lose each turn that it is starving.
If starving for several reasons, loss is max of starvation losses,
not the sum.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-as-occupant} u m -> n%
This table is the consumption by a unit of type @var{u1} when it is
an occupant, expressed as a percentage of its @code{base-consumption}.
This is useful for units such as planes which always consume fuel
in the air but not on the ground.
Defaults to @code{100}.
@end deffn

@node Terrain Production and Consumption, Supply Lines, Unit Production and Consumption, Backdrop Economy Parameters

@subsection Terrain Production and Consumption

Materials may be produced by cells, redistributed, and also taken up
by units.  Some amount of material may need to stay in the cell's storage,
or the type of terrain might change.  Exhaustion is tested after all consumption
has been accounted for.

@deffn Table @code{terrain-production} t m -> n
This table is the amount of each material @var{m} produced by a cell of the given
type @var{t} in each turn.
Defaults to @code{0}.
@end deffn

@deffn Table @code{terrain-consumption} t m -> n
This table is the amount of material @var{m} consumed by a cell of type @var{t}
each turn.
If insufficient material is available, then the terrain may change type.
Defaults to @code{0}.
@end deffn

@deffn Table @code{change-on-exhaustion-chance} t m -> n%
This table is the chance that a cell of type @var{t}, with no supply of material
of type @var{m}, will become exhausted and change to its exhausted type.
@end deffn

@deffn Table @code{terrain-exhaustion-type} t1 m -> t2
If @var{t2} is not @code{non-terrain},
then this table says that any cell with terrain @var{t1}
that is exhausted will change to @var{t2}.
If several materials are
exhausted in the same turn, then the lowest-numbered material type
will determine the new terrain type.
Defaults to @code{non-terrain}.
@end deffn

@deffn Table @code{people-consumption} m1 m2 -> n
This table is the base consumption per turn
by people of type @var{m1} of each other material type @var{m2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{people-production} m1 m2 -> n
This table is the people of type @var{m1} base production per turn
of each other material type @var{m2}.
Defaults to @code{0}.
@end deffn

@node Supply Lines,  , Terrain Production and Consumption, Backdrop Economy Parameters

@subsection Supply Lines

In real life, material production and consumption rarely occur in the same place
at the same time.
For some games, the player must transfer materials
manually, by loading and unloading from units.
However, this can be time-consuming and difficult,
and is best reserved for scarce and/or
valuable materials.
For more common materials, @i{Xconq} provides @dfn{supply lines}.

@deffn Table @code{in-length} u1 m -> dist
@end deffn
@deffn Table @code{out-length} u2 m -> dist
These two tables together determine the length of supply lines
between units.  The given type of material can only be transferred from
unit type @var{u1} to unit type @var{u2}
if the distance is less than the minimum of
the @code{in-length} of @var{u1} and the @code{out-length} of @var{u2}.
For instance, the @code{in-length} for a fighter's fuel might be 3 cells,
while the @code{out-length} of fuel from a city is 4 cells.
Then the fighter will be constantly supplied with fuel
when within 3 cells of a city.
If the fighter's out-length is -1, it will never
transfer any fuel to the city.
An in- or out-length of @code{0} means that the two units must be
in the same cell,
while a negative length disables the automatic transfer completely.
Long @code{out-length} lines should be used sparingly,
since the algorithm uses the @code{out-length} to
define a radius of search for units to be resupplied.
Both default to @code{0}.
@end deffn

@c @node Backdrop Trade, Backdrop Taxation, Supply Lines, Backdrop Economy Parameters
@c
@c @subsection Backdrop Trade
@c
@c [not yet implemented]
@c
@c To move materials automatically between cells,
@c you must define the demand and supply relationships,
@c as well as the rate and distance that materials can move.
@c
@c Demand for a material originates with consumption and
@c construction needs, issuing either from a side or from
@c some other part of the economy.
@c
@c @node Backdrop Taxation, Material Conversion, Backdrop Trade, Backdrop Economy Parameters
@c
@c @subsection Backdrop Taxation
@c
@c [not yet implemented]
@c
@c A side can set a taxation rate, which is the amount of material
@c that will be taken from the cell-based economy and given to units
@c on that side.
@c
@c Taxes may be negative, which will have the effect of returning
@c materials from units back to cells.
@c
@c Taxation is the last step in economic calculations.
@c
@c @node Material Conversion,  , Backdrop Taxation, Backdrop Economy Parameters
@c
@c @subsection Material Conversion
@c
@c [not yet implemented]
@c
@c Some types of materials can be converted or combined into other types
@c of materials.
@c

@node Random Events, Dates and Time, Backdrop Economy Parameters, Reference Manual

@section Random Events

@deffn GlobalVariable @code{random-events} method-list
This variable is a list of random event methods
that will be run at the end of each turn.
The list is not ordered.
@end deffn

@menu
* Terrain Attrition::
* Terrain Accident::
* Unit Revolt::
* Unit Surrender::
@end menu

@node Terrain Attrition, Terrain Accident, Random Events, Random Events

@subsection Terrain Attrition

Attrition is the automatic loss of hit points due to being in certain types
of terrain.

@deffn Method @code{attrition-in-terrain}
For every unit not in a transport,
this method computes the chance to lose hit points,
then damages the unit accordingly.
This method runs once per turn.
@end deffn

@deffn Table @code{attrition} u t -> .01hp
This table is the rate of loss of hp per turn.
The terrain used is cell or connection terrain as appropriate for
the unit's position.
Defaults to @code{0}.
@end deffn

@node Terrain Accident, Unit Revolt, Terrain Attrition, Random Events

@subsection Terrain Accident

Accidents result in the damage or disappearance of a unit in the open
in some kinds of terrain.

@deffn Method @code{accidents-in-terrain}
For every unit not in a transport,
this method computes the chance to be hit or to vanish completely.
This method runs once per turn.
@end deffn

@deffn Table @code{accident-hit-chance} u t -> .01n%
This table is the chance of the unit being hit while in the given terrain.
Defaults to @code{0}.
@end deffn

@deffn Table @code{accident-damage} u t -> hp
This table is the hp that will be lost in an accident.
Defaults to @code{0}.
@end deffn

@deffn Table @code{accident-vanish-chance} u t -> .01n%
This table is the chance of the unit simply vanishing while in the given terrain.
Defaults to @code{0}.
@end deffn

@node Unit Revolt, Unit Surrender, Terrain Accident, Random Events

@subsection Unit Revolt

Revolt is a spontaneous change of side,
occurring in place of a side-given unit action.
The new side may be none (independence) or another side.

@deffn Method @code{units-revolt}
For each completed unit, this method decides whether the unit revolts,
then changes its side.
@end deffn

@deffn UnitTypeProperty @code{revolt-chance} .01n%
This property is the chance for the unit to revolt spontaneously.
Defaults to @code{0}.
@end deffn

@node Unit Surrender, , Unit Revolt, Random Events

@subsection Unit Surrender

@deffn Method @code{units-surrender}
For each completed unit, this method checks whether the unit will surrender
to a nearby unfriendly unit.
@end deffn

@deffn Table @code{surrender-chance} u1 u2 -> .01n%
This table is the chance that a unit of type @var{u1} will change its side
to match the side of a unit @var{u2} that is within the @code{surrender-range}
for the two types.
Defaults to @code{0}.
@end deffn

@deffn Table @code{surrender-range} u1 u2 -> dist
This table is the distance out to which a unit of type @var{u1}
will surrender to a unit of type @var{u2}.
Defaults to @code{1}.
@end deffn

@node Dates and Time, Image Families, Random Events, Reference Manual

@section Dates and Time

@deffn GlobalVariable @code{turn} n
This variable is the number of the current turn.
Defaults to @code{0}.
@end deffn

Note that the first turn of a game is actually turn 1.
Pre-game activities happen during ``turn 0''.

@menu
* Game Length::
* Calendar::
* Real Time::
@end menu

@node Game Length, Calendar, Dates and Time, Dates and Time

@subsection Game Length

@deffn GlobalVariable @code{last-turn} n
This variable is the number
of the last turn.
Defaults to @code{-1}, which means that there is no limit on the number
of turns.
@end deffn

@deffn GlobalVariable @code{extra-turn-chance} n%
This variable is the chance that the game will go one more turn
after the @code{last-turn}.
@end deffn

@i{Xconq} is currently limited to games of 32,767 turns.

@node Calendar, Real Time, Game Length, Dates and Time

@subsection Calendar

You can make @i{Xconq} display game time as a calendar date,
rather than as a simple turn number.

@deffn GlobalVariable @code{calendar} type data@dots{}
This variable is the description of the calendar type that will be used.
If @code{none}, then turns will be reported numerically starting
from @code{1}.  If @code{usual}, then the standard Gregorian
calendar will be used.
(Other calendars may be supported in the future.)
Defaults to @code{()}, which is equivalent to @code{(number "turn")}.

For the @code{usual} calendar, the @var{data} defines how long a turn is,
in terms of the calendar.
For instance, a time measure of @code{"day"}
(and a base date of @code{"1 Jan 1900"}) will result in turns
@code{"1 Jan 1900"}, @code{"2 Jan 1900"}, etc,
while a date unit of @code{"year"}
will yield just @code{"1900"}, @code{"1901"}, and so forth.

If the numeric or @code{number} calendar is in use, then a @var{data} of @code{"day"}
will yield @code{"day 1"}, @code{"day 2"}, etc.

The rest of this variable lists the name of each season
and the turns within a year for which it is appropriate.
A twelve-turn year with four seasons could be
@example
((0 2 "winter") (3 5 "spring") (6 8 "summer") (9 11 "autumn"))
@end example
If any number ranges overlap, then the first match will be used,
while if a particular turn has no named season, then it will go
unnamed in the display.
@end deffn

@deffn Symbol @code{none}
@end deffn
@deffn Symbol @code{usual}
@end deffn

@deffn GlobalVariable @code{initial-date} str
This variable is the date, in the specified calendar system, of the first turn.
Defaults to @code{""}, which has the effect of setting the initial date
to be whatever the calendar does with turn number 1.
@end deffn

@node Real Time, , Calendar, Dates and Time

@subsection Real Time

A game may also be limited in real time.

@deffn GlobalVariable @code{real-time-for-game} seconds
@end deffn

@deffn GlobalVariable @code{real-time-per-turn} seconds
@end deffn

@deffn GlobalVariable @code{real-time-per-side} seconds
@end deffn

@deffn GlobalVariable @code{elapsed-real-time} seconds
This is the difference in real time between the start of the game
and its current state.
@end deffn

@node Image Families, Other Forms, Dates and Time, Reference Manual

@section Image Families

The @code{imf} form defines graphical images in a
platform-independent way.
An @i{image family} is a named collection of images of varying
sizes and depths.

@deffn Form @code{imf} name [ properties ] [ images ]
This form declares an image family to exist, with the name @var{name}
and @var{properties}, and consisting of the specified @var{images}.
Each image has the form
@code{((@var{w} @var{h} [tile]) [@var{properties}] (@var{type} @var{data}...) ...)},
where @var{w} and @var{h} are its width and height, respectively,
the @var{type} may be one of @code{color}, @code{mono}, or @code{mask},
and the @var{data} consists of strings of hexadecimal digits.
The data strings may include slashes, which have no effect on interpretation,
but are useful to indicate each row of an image.
Color images may also have additional properties, which come between the
@var{type} and the @var{data}.

The family's @var{name} may consist only of alphabetic characters,
decimal digits, and hyphens or underscores.  Upper- and lower-case
characters are equivalent, as are hyphens and underscores.  The
canonical form of the name is lowercase with hyphens.

Multiple forms with the same name may occur, and each adds to the family,
overwriting individual image parts that are of the same size and depth.

@end deffn

@deffn Symbol @code{tile}
If this symbol appears following the dimensions of an image,
it indicates that the image is a pattern tile rather than a single image.
@end deffn

@deffn ImageProperty @code{actual} w h
This property is the actual size of the image data.
@end deffn

@deffn ImageProperty @code{embed} name
This property specifies that another image, similar to the image family
named by @var{name}, is already embedded within the image, and so @i{Xconq}
need not superimpose such an image itself.  This may occur when an image
has a ``builtin'' side emblem, or is readily identifiable as belonging
to a particular side, and it would be redundant for @i{Xconq} to add an
emblem when displaying a unit.
@end deffn

@deffn ImageProperty @code{embed-at} x y
This property specifies that the area of the image at @i{x,y} is suitable
for the display of an emblem.
@end deffn

@deffn ImageProperty @code{embed-size} w h
This property specifies the dimensions of the area available for an
emblem.
@end deffn

@deffn ImageProperty @code{mono} data @dots{}
This property indicates that the data represents a monochrome image.
@end deffn

@deffn ImageProperty @code{mask} data @dots{}
This property indicates that the data represents a mask.
@end deffn

@deffn ImageProperty @code{color} [ properties ] data @dots{}
This property indicates that the data represents a color image.
@end deffn

@deffn ColorImageProperty @code{pixel-size} n
This property is the number of bits used to encode each pixel.
@end deffn

@deffn ColorImageProperty @code{row-bytes} n
This property is the number of bytes in each row of the image.
@end deffn

@deffn ColorImageProperty @code{palette} [ name | (index r g b) @dots{} ]
This property is the color palette that should be used with the image.
@end deffn

@deffn Form @code{palette} name (index r g b) @dots{}
This form defines a palette with the given @var{name}.
@end deffn

@deffn Form @code{color} name r g b
This form names the color.
@end deffn

Note that for the purposes of stability and change tracking,
tools that generate image families use a more restricted format.
This format requires a separate imf form for each size of image,
the size is on the same line as the imf name, and each image/mask
is on a separate line, indented by 2. (See the existing library imf
files for further detail.)

@node Other Forms, Files and Directories, Image Families, Reference Manual

@section Other Forms

GDL forms in this section are those that do not really fit anywhere
else.

@menu
* Default Display Style::
* The Random State::
* Debugging Support::
@end menu

@deffn UnitTypeProperty @code{name-internal} str
Internally used type name.
@end deffn

@node Default Display Style, The Random State, , Other Forms

@subsection Default Display Style

The exact style of display depends on the user interface and
on user preferences,
but for some games, you may want to encourage a particular style
by making it be the default.

@deffn GlobalVariable @code{unseen-char} str
This variable is a string whose first character will be used to
represent unexplored terrain.
If the string consists of two characters, the second char will be
scattered throughout a field of the first char.
Defaults to @code{""}.
@end deffn

@deffn GlobalVariable @code{unseen-color} str
This variable is the name of a color that will be used to
represent unexplored terrain.
Defaults to @code{""}.
@end deffn

@deffn GlobalVariable @code{unseen-image-name} str
This variable is the name of an image that will be used to
represent unexplored terrain.
Defaults to @code{""}.
@end deffn

@deffn GlobalVariable @code{grid-color} str
This variable is the name of a color to use to draw the
cell-separating grid.
Defaults to @code{""}.
@end deffn

@node The Random State, Debugging Support, Default Display Style, Other Forms

@subsection The Random State

It is useful to be able to restart the random number generator
consistently.

@deffn GlobalVariable @code{random-state} n
This variable is the state of the random number generator.
If this is not used, then the initial state of the random number
generator will be set in a system-dependent way.
@end deffn

@node Debugging Support,  , The Random State, Other Forms

@subsection Debugging Support

@deffn Form @code{print} value
This form prints to a console or file (depending on the interface)
the object @var{value}, in GDL syntax.
@end deffn

@node Files and Directories,  , Other Forms, Reference Manual

@section Files and Directories

This section defines file and directory structure for using GDL.  This is not required;
for instance, an implementation may choose to handle GDL by reading it from strings
compiled into the program.  However, the standard @i{Xconq} library and implementation
does adhere to the conventions described here.

A game module is a set of forms in a text file, which has an extension of @code{.g}.

By convention, the first form in the file is a @code{game-module} form that defines
properties of the module.  If the interface has any sort of preview for a particular
module, it can then read only the first form, rather than the entire file.

Some interfaces include a game selection dialog, which lists a set of games from which
to choose, along with a little information about each.  The file @code{game.dir} in
the library directory contains this list, which is simply a list of module name strings:
@example
(  ;; games that should appear in new game selection dialogs
"1756"
"cave"
"cherbourg"
"classic"
"coral-sea"
"crater-lake"
)
@end example

@i{Xconq} does not currently enforce any sort of standard on file names,
but for maximum portability, the file name should not include mixed case,
it should consist only of alphabetic and numeric characters and hyphen,
and should be less than 12 characters in length, with 8 of those distinct
from any other name in the same directory.  Since @i{Xconq} implementations
typically use the file name as a way to find modules,
these restrictions should apply to module names as well.

Image files are library files with the extension @code{.imf}.  Usually each image
file contains a group of images related in some way, perhaps by a common theme
or by use in a particular game. @i{Xconq} implementations find images either by
a method specific to the platform (such as resource files), or by looking up the
image's location in the image directory @code{imf.dir}.
The image directory is just a set of pairs of image name and imf file, with markers
at beginning and end of the file:
@example
ImageFamilyName FileName
amulet fantasy.imf
ant insects.imf
anvil-and-crown fantasy.imf
ap standard.imf
archer ancient.imf
. .
@end example
Note that while @code{game.dir} is a GDL-syntax form, @code{imf.dir} is not.
It should rarely be necessary to modify @code{imf.dir} directly; the scripts
@code{makedir.sh} and @code{makedir.pl} in the standard library directory
are Unix shell and Perl scripts, each of which will generate @code{imf.dir} from a
given list of files, such as @code{*.imf} in the library.  You should run
one of these after adding to a library image file.